Guide

Postgres MCP Servers: Which One to Give Your Agent

The Supabase MCP server, Postgres MCP Pro, Google's MCP Toolbox, the archived reference server and governed-dataset servers: what each lets an agent do to your database, and how to run it read-only.

By Governed Ground Truth Editors · Checked against its sources on · MCP and Headless Analytics

A Postgres MCP server is the piece that lets an AI client such as Claude, Cursor or your own agent talk to a Postgres database over the Model Context Protocol. The client sees a list of tools (list the tables, run this SQL, explain this query) and the server turns each call into work against the database.

The servers differ less in how they connect than in what they let the agent do. Some hand the agent arbitrary SQL. Some add migrations, branches and project management. Some expose only the named queries you wrote. And some keep the agent off Postgres entirely and serve modeled datasets instead. Which one is right depends on whether the agent is helping you build, helping you tune, or answering questions in production.

The options, side by side

ServerWhat the agent can doBest for
Supabase MCP serverArbitrary SQL, migrations, logs, Edge Functions, branches and project management, grouped into feature groups you can switch offSupabase teams building and debugging with an AI coding tool
Postgres MCP ProSQL plus EXPLAIN plans, slow-query reports, index recommendations and health checks; unrestricted or restricted (read-only) modeTuning and inspecting any Postgres, managed or self-hosted
MCP Toolbox for DatabasesEither prebuilt generic tools (list tables, run SQL) or only the named, parameterised queries you define in tools.yamlGiving an agent a fixed set of approved queries instead of open SQL
Reference Postgres server (@modelcontextprotocol/server-postgres)One query tool that runs inside a READ ONLY transaction; table schemas as MCP resourcesReading the code to see how a minimal Postgres MCP server works
A governed-dataset server (for example, Dreambase)Pre-modeled datasets and named metrics; the agent never reaches the production databaseAgents answering business questions in production, where every number has to match

Supabase MCP server

Maintained by: Supabase · supabase.com/docs/guides/getting-started/mcp

Best for: Supabase teams building and debugging with an AI coding tool.

Supabase hosts the server at https://mcp.supabase.com/mcp. Your MCP client signs you in to Supabase through the browser, so there is no connection string or personal access token to paste. Running Supabase locally, the CLI serves it at http://localhost:54321/mcp with a smaller set of tools.

Its tools are grouped: database (list_tables, apply_migration, execute_sql and more), debugging (logs and advisors), development, Edge Functions, account management, docs, branching and storage. Three URL parameters narrow it: project_ref scopes it to one project and drops the account tools, read_only=true runs every query as a read-only Postgres user, and features picks the groups to load.

Watch out for

  • It works with your own developer permissions. Supabase's docs say not to give it to customers or end users, and to keep it as an internal developer tool.
  • Supabase wraps SQL results in instructions that discourage the model from following commands found in the data, and says plainly that this is not foolproof against prompt injection. Keep manual approval of tool calls on.
  • Before pointing it at a production project, Supabase recommends project scoping, read-only mode and only the feature groups you need.
{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs"
    }
  }
}
A project-scoped, read-only connection, database and docs tools only

Postgres MCP Pro

Maintained by: Crystal DBA (open source, MIT) · github.com/crystaldba/postgres-mcp

Best for: Tuning and inspecting any Postgres, managed or self-hosted.

A Python server, run with Docker, pipx or uv, that connects to any Postgres from a DATABASE_URI connection string. It speaks stdio, or SSE when several clients should share one server.

Beyond list_schemas, get_object_details and execute_sql, it ships DBA tools: explain_query (including with hypothetical indexes), get_top_queries, analyze_workload_indexes, analyze_query_indexes and analyze_db_health, whose checks are adapted from PgHero. Index tuning and the workload tools need the pg_stat_statements and hypopg extensions.

It has two access modes. Unrestricted allows reads and writes, schema changes included, and is meant for development. Restricted runs read-only transactions, limits execution time and parses each statement first to reject COMMIT and ROLLBACK, so a query cannot end the read-only transaction and start a writable one.

Watch out for

  • Its own examples use --access-mode=unrestricted. Switch to --access-mode=restricted for anything that matters.
  • The maintainers note that the read-only protection can be circumvented if unsafe stored-procedure languages are enabled on the database.
  • Credentials sit in the MCP client's config file, which few clients store securely. A role that can only read is still the stronger guarantee (see below).
{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DATABASE_URI",
               "crystaldba/postgres-mcp", "--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://mcp_reader:<password>@<host>:5432/<db>"
      }
    }
  }
}
Restricted mode with Docker

MCP Toolbox for Databases

Maintained by: Google (open source, Apache 2.0) · github.com/googleapis/mcp-toolbox

Best for: Giving an agent a fixed set of approved queries instead of open SQL.

Run with --prebuilt=postgres and it gives the agent generic tools such as list_tables and execute_sql. Its stronger use is the other mode: a tools.yaml file that declares a source (your Postgres) and tools, each one a SQL statement with typed parameters and a description the model reads.

The agent can call search-orders-by-customer with a customer id, and nothing else. Toolsets group tools per agent or application, and the server handles connection pooling and emits OpenTelemetry metrics and traces.

Watch out for

  • The prebuilt Postgres tools include open SQL. The safety comes from writing your own tools.yaml and not loading the prebuilt set alongside it.
  • Every new question needs a new tool, which is the point: someone reviews each query before an agent can run it.
  • It supports many databases beyond Postgres; check its docs for the current list and for Google Cloud's managed MCP servers, a separate hosted option.
kind: source
name: app-db
type: postgres
host: <host>
port: 5432
database: <db>
user: mcp_reader
password: <password>
---
kind: tool
name: orders-for-customer
type: postgres-sql
source: app-db
description: Orders placed by one customer, newest first.
parameters:
  - name: customer_id
    type: string
    description: The customer's id.
statement: SELECT id, total, created_at FROM orders WHERE customer_id = $1 ORDER BY created_at DESC LIMIT 50;
One named, parameterised tool in tools.yaml

Reference Postgres server (@modelcontextprotocol/server-postgres)

Maintained by: Model Context Protocol project, now archived · github.com/modelcontextprotocol/servers-archived/tree/main/src/postgres

Best for: Reading the code to see how a minimal Postgres MCP server works.

The original example server: a single query tool whose SQL runs inside a read-only transaction, and each table's column names and types published as a resource at postgres://<host>/<table>/schema.

Watch out for

  • It has moved to the modelcontextprotocol/servers-archived repository, and its npm package is marked deprecated: "Archived and unmaintained; no security guarantees." Many older tutorials still point to it. Use a maintained server instead.
  • A read-only transaction on its own can be ended by a statement such as ROLLBACK followed by a write; this is the gap Postgres MCP Pro's statement parsing exists to close.

A governed-dataset server (for example, Dreambase)

Maintained by: Analytics-layer vendors; Dreambase is one (commercial) · dreambase.com

Best for: Agents answering business questions in production, where every number has to match.

Every server above, however locked down, still lets the agent query your database. A governed-dataset server moves the boundary: data is modeled ahead of time into datasets and metrics with agreed definitions, and the MCP server exposes those. The agent asks for weekly active accounts; it does not write the SQL that decides what an active account is.

Dreambase, built for teams on Supabase, works this way: it models Postgres data into governed Parquet datasets queried with DuckDB and exposes them, with pre-calculated metrics, through a single MCP server, so agents never touch the production database.

Watch out for

  • The agent can only answer what has been modeled. Questions outside the datasets need a new dataset, or a developer tool from the list above.
  • How fresh the data is depends on how often the datasets are rebuilt; ask the vendor and check it against your use.

Which one to pick

  • Building or debugging a Supabase app in your editor: The Supabase MCP server, scoped to a development project or branch. Add read_only=true whenever it can see real data.
  • Finding slow queries and missing indexes: Postgres MCP Pro in restricted mode against a replica or staging copy, with pg_stat_statements and hypopg installed.
  • An agent in your product that runs a known set of lookups: MCP Toolbox for Databases with your own tools.yaml, so each query is one you reviewed.
  • Agents answering metric questions for the business: A governed-dataset server, so the agent and your dashboards read the same definitions and the agent stays off production.
  • Following a tutorial that uses @modelcontextprotocol/server-postgres: Swap in a maintained server from this list; the reference server is archived.

Running any of them safely

Whichever server you choose, the database should enforce the limits, not the server or the prompt. A server's read-only mode is a useful second layer; a role that cannot write is the first.

  1. Give the server its own role. Never the postgres superuser, and on Supabase never the service_role key, which bypasses row-level security. Grant SELECT on the schemas the agent needs and nothing else.
  2. Point it at a replica or a copy. Agent queries are unpredictable. A read replica, branch or staging database keeps a runaway query from slowing the app your customers use.
  3. Cap query time. Set statement_timeout on the role so one expensive query cannot hold connections.
  4. Treat data as untrusted input. Rows can contain text written to steer the model (prompt injection). Keep approval of tool calls on, and never give one agent both untrusted data and write access.
  5. Keep a record. Log which role ran which statement (pgaudit, or your provider's logs) so you can answer what the agent read.
CREATE ROLE mcp_reader LOGIN PASSWORD '<generated-secret>';
GRANT CONNECT ON DATABASE <db> TO mcp_reader;
GRANT USAGE ON SCHEMA public TO mcp_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
ALTER ROLE mcp_reader SET default_transaction_read_only = on;
ALTER ROLE mcp_reader SET statement_timeout = '10s';
A read-only role for an MCP server

The GRANTs are what stop writes: default_transaction_read_only is only a default, and a session can turn it off. Tables created later need their own GRANT (or ALTER DEFAULT PRIVILEGES). With row-level security on a table, the role sees only the rows a policy gives it.

Questions people ask

Is there an official Postgres MCP server?

The Model Context Protocol project's own reference server is archived and unmaintained. Supabase maintains the Supabase MCP server for its platform; for other Postgres hosts, Postgres MCP Pro and Google's MCP Toolbox for Databases are maintained open-source options.

Can I use the Supabase MCP server with a Postgres database that isn't on Supabase?

No. It works through your Supabase account and projects. For any other Postgres, use a server that takes a connection string, such as Postgres MCP Pro or MCP Toolbox for Databases. Those also work against a Supabase database's connection string.

Does read-only mode make it safe to connect production?

It stops writes, not reads. An agent in read-only mode can still read every table its role can see and pass that data on, and it can still run expensive queries. Scope the role, cap query time, prefer a replica, and for questions answered in production consider a governed-dataset server instead.

How do I add a Postgres MCP server to Claude Code or Cursor?

Both read an mcpServers block like the examples above: Claude Code from .mcp.json in your project or claude mcp add, Cursor from .cursor/mcp.json. Each server's docs list the exact steps per client.

What does a Postgres MCP server cost?

Postgres MCP Pro, MCP Toolbox and the reference server are free, open-source software; you pay for the database they connect to. Supabase's MCP server is part of the Supabase platform, and some of its tools (creating projects or branches) can add charges, which it asks you to confirm. Check Supabase's and any vendor's current pricing pages.

Sources

Tool names, options and defaults change between releases. Check each project's current docs before you rely on a detail here.

Dreambase, named in this guide, has sponsored coverage on this site.

Further reading