What it does

Three core tools: list_tables (every table the role can see), describe_table (columns, types, comments, indexes), and query (run an arbitrary SELECT). Some forks add execute (DDL / DML) and transaction wrappers. The canonical version stays close to read.

When you actually need it

Plain-English questions over your own database. “How many users signed up last week, broken down by source?” — the agent calls list_tables, picks the right table from the schema, drafts the query, runs it, returns the answer with the SQL it ran. The honesty of having the agent show its query is the whole point.

Setup

"postgres": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-postgres",
    "postgresql://agent:password@localhost:5432/mydb"
  ]
}

The connection string carries the credentials. Two non-negotiables:

1. Use a dedicated role. Not postgres. Not your app’s role. A new role with only CONNECT to the database, only SELECT on the tables you’ve thought about, and a statement_timeout set short.
2. Default to read-only. Add default_transaction_read_only = on for the role.

CREATE ROLE agent_reader LOGIN PASSWORD 'rotate-this';
GRANT CONNECT ON DATABASE mydb TO agent_reader;
GRANT USAGE ON SCHEMA public TO agent_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO agent_reader;
ALTER ROLE agent_reader SET default_transaction_read_only = on;
ALTER ROLE agent_reader SET statement_timeout = '30s';

Now even if the agent invents a DROP TABLE users, Postgres refuses.

The catch

The agent will sometimes write a query that returns a million rows. It will sometimes run a query that takes ten minutes. The MCP server doesn’t paginate — it returns whatever Postgres returns, and your context window is the limit.

Defensive moves: the role-level statement_timeout, plus a prompt rule (“if a query would return more than 200 rows, narrow it first”), plus a follow-the-money habit of watching pg_stat_activity while the agent is exploring an unfamiliar database.