Supabase MCP Server: Complete Guide

One-sentence definition

The Supabase MCP server is the official Model Context Protocol (MCP) server — maintained under supabase-community/supabase-mcp — that exposes your Supabase project to an AI agent as a set of tools, so the model can run SQL, manage schema and migrations, deploy Edge Functions, read logs, manage branches, and search the docs. MCP is the JSON-RPC wire format that lets any LLM client talk to any tool server; the Supabase MCP server is the Supabase-shaped implementation of that.

It is the engine behind the “build an app with an AI agent” loop: you describe a feature in Cursor or Claude, and the agent creates the table, writes the migration, and queries the result without you leaving the editor. You can view it in our catalog or read our explainer on what MCP is first if the protocol itself is new to you.

Why it exists

Before MCP, wiring an agent to a database meant hand-writing a tool layer: a function for “run query,” another for “list tables,” a serialization format, an auth story, and a prompt that taught the model how to call all of it. Every team rebuilt that scaffolding, and every rebuild drifted. The agent that worked in Cursor needed porting to work in Claude.

Supabase shipped its official MCP server in April 2025 to collapse that work into one config block. One server, one protocol, every MCP-speaking client — Cursor, Claude, VS Code Copilot, Windsurf, Claude Code. The agent gets a stable, documented tool surface over a Supabase project, and Supabase controls what that surface exposes. The launch post describes over 20 tools across schema, data, config, logs, and functions.

Takeaway: it exists to make “agent + Postgres” a config line instead of a project. That convenience is exactly why the security section later matters so much.

Mental model: the named pieces

Five pieces, and once you can name them the config stops looking like magic.

The fifth piece is the transport: the long-standing local form runs the server as a subprocess via npx (stdio), while the newer hosted form points your client at the remote endpoint https://mcp.supabase.com/mcp over Streamable HTTP. Same tools, same flags — only the spelling differs (CLI flags for stdio, URL query params for remote).

Install: the smallest working example

Two paths. Pick one. The clickable panel below pulls the exact, current config for every client straight from our catalog, so it stays in sync as Supabase ships changes — tap your client (Cursor, Claude Code, VS Code, Windsurf) and copy.

One-line install · Supabase MCP Server

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Path A — local (stdio via npx). The config that most setup guides have shown for the longest. Note the two flags doing the safety work, --read-only and --project-ref:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<your-project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}

Create the token under Account → Access Tokens in the Supabase dashboard, and keep it in the env block (not the args) so it stays out of version control if you commit the config. Restart your MCP client after setting it.

Path B — remote (Streamable HTTP). Supabase’s hosted endpoint. The same two safety controls move into URL query params (read_only=true, project_ref) and the token rides in an Authorization header:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=<ref>&read_only=true",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}

Whichever path you take, the install is not finished until both read_only and the project scope are set. We treat a config without them as unfinished, for reasons the security section makes concrete.

Feature groups: turn off what you don’t need

The tools are bundled into feature groups. You enable a subset with --features (stdio) or features (remote URL). Fewer groups means a smaller tool surface, a smaller prompt, and a smaller blast radius.

*account tools disable themselves once you set a project ref — scoping and account-level control are mutually exclusive by design. Takeaway: if your agent only needs to write app code against a schema, run --features=database,docs and nothing else.

The security problem you can’t skip

In mid-2025, the security firm General Analysis published a disclosure (it reached the top of Hacker News, 800-plus points) showing a clean attack. A developer used an IDE agent to read recent support tickets through the Supabase MCP server. One ticket’s body was not a real complaint — it was a set of instructions written for the model. The agent, running with service_role credentials that bypass row-level security, followed those instructions: it queried a sensitive tokens table and wrote the result back into the ticket thread, where the attacker could read it.

That is prompt injection: the LLM cannot tell data apart from instructions. As General Analysis put it, models “process all text the same way; whether it is data/context or user instructions.” The database row was data to you and a command to the model.

Simon Willison framed the same incident as his “lethal trifecta”: the attack needs three things together — access to private data, exposure to untrusted instructions, and a way to exfiltrate. Remove any one leg and the attack collapses. That is the entire strategy for hardening this server.

How to harden it (the three legs)

Supabase’s own guidance maps almost one-to-one onto the trifecta. Apply all of it; none of it is optional on real data.

1. Don’t connect to production. Point the server at a development project, not your live one. Supabase states this plainly: the MCP server is designed for development and testing. This removes the “private data” leg by making the data non-sensitive.
2. Run read-only. The --read-only flag executes queries as a read-only Postgres user, removing the “exfiltrate by writing back” leg. In the General Analysis attack, the write-back into the ticket was how the attacker actually saw the data.
3. Scope to one project. --project-ref bounds the blast radius to a single project and disables account-level tools.
4. Keep manual tool approval on. Most clients (Cursor, Claude) ask you to approve each tool call. Supabase recommends never disabling that. It is your last human checkpoint before a query runs.

What we got wrong

Three assumptions that cost us, so you can skip them.

We thought read-only made it “safe.” It does not. It closes one leg of the trifecta. We ran a read-only, production-scoped server early on and felt covered — until the Willison piece made it obvious that a read-only agent reading a poisoned row can still surface secrets in its own output. Read-only is the floor, not the ceiling.

We left every feature group on. The defaults enable database, functions, development, debugging, docs, and account. We only needed database and docs for the task. Every extra group is more tools in the prompt and more capability an injected instruction can reach. Trim to what the job needs.

We pasted the token into args. Then committed the config. The token belongs in the env block (or a secret manager), never in a command line that lands in git history. Rotate it if you have ever done this.

Wrong vs right patterns

# production ref, full write access, all features
npx -y @supabase/mcp-server-supabase@latest \
  --project-ref=<PROD_REF>

# dev ref, read-only, minimal features
npx -y @supabase/mcp-server-supabase@latest \
  --read-only \
  --project-ref=<DEV_REF> \
  --features=database,docs

Common mistakes

• Omitting --read-only on real data. Root cause: the flag is opt-in, not default. If you forget it, the agent can write — and write-back is the exfiltration step in the documented attack.
• Pointing it at production. Root cause: it works, and it is tempting. Supabase explicitly advises against it. Use a dev project or a branch.
• Disabling manual tool approval. Root cause: approving every call is friction, so people auto-accept. That deletes the last human in the loop.
• Token in version control. Root cause: putting it in args instead of env. Anyone with repo read access then has your Supabase access token.
• Client doesn’t speak Streamable HTTP. Root cause: an older client build. Symptom is empty tool lists or connection errors on the remote endpoint. Fall back to the local npx stdio config.

Who it is for (and who it isn’t)

Use it if: you build on Supabase and want an agent that designs schema, writes migrations, and queries data from inside Cursor, Claude, or VS Code; you work primarily against development projects or branches; you are comfortable setting two flags before you trust it.

Skip it (or lock it down hard) if: your only Supabase project holds production user data with no dev mirror; you cannot enforce read-only and project scoping; you plan to expose the agent to content submitted by untrusted users (tickets, comments, form input) while it can also read private tables. That combination is the lethal trifecta by construction.

Community signal

The loudest community moment for this server was not a launch tweet — it was the security disclosure. The General Analysis write-up, “Supabase MCP can leak your entire SQL database,” drew 800-plus points and several hundred comments on Hacker News. The thread is the best primary read on how practitioners reacted: a mix of “this is inherent to giving an LLM database access” and “the defaults should be safer.”

The contrarian-but-fair voice is Simon Willison’s. He does not say “don’t use it” — he says the docs should be far more explicit about the trifecta, and that read-only alone gives a false sense of safety. That criticism landed: Supabase’s guidance now leads with read-only, project scoping, and a clear “don’t connect to production” warning. The honest summary is that the ecosystem argued its way to safer defaults in public.

(We looked for a verifiable first-party launch tweet to embed here. The X oEmbed endpoint is gated and we do not publish tweet IDs we can’t verify, so we cite Supabase’s official launch post instead.)

The Verdict

The bigger picture

The Supabase incident became a reference case for a general truth about agent tooling: the moment an LLM can read untrusted content and act on a privileged system, prompt injection is a live threat, not an edge case. This is not a Supabase flaw so much as an MCP-era reality — the same shape recurs with any database, email, or filesystem MCP server.

The durable answers are converging: least-privilege scopes, read-only by default, human-in-the-loop approval, and keeping untrusted data away from privileged agents. Supabase moving its guidance toward read-only and project scoping is part of that industry-wide correction. Browse other database MCP servers or our roundup of the best MCP servers for databases and Supabase — and apply the same trifecta lens to every one.

Frequently asked questions

Glossary

MCP

Model Context Protocol — the JSON-RPC standard letting any LLM client call any tool server.

Prompt injection

Untrusted text that the model reads as instructions instead of as data.

Lethal trifecta

Private-data access + untrusted instructions + exfiltration path, all at once.

Read-only mode

--read-only; runs queries as a read-only Postgres user — no writes.

Project scoping

--project-ref; bounds the server to one project, disabling account tools.

service_role

A Supabase key that bypasses row-level security — full table access.

RLS

Row-level security; Postgres policies that restrict which rows a role can see.

Feature group

A toggleable bundle of tools enabled via --features.

stdio transport

Running the server locally as a subprocess via npx.

Streamable HTTP

The remote transport for the hosted mcp.supabase.com/mcp endpoint.

Sources & links

Primary

• Repository: github.com/supabase-community/supabase-mcp
• Official docs: supabase.com/docs/guides/getting-started/mcp and /guides/ai-tools/mcp
• Launch post: supabase.com/blog/mcp-server

Community & security

• General Analysis disclosure: generalanalysis.com/blog/supabase-mcp-blog
• Hacker News thread (800+ points): news.ycombinator.com/item?id=44502318
• Simon Willison, “Supabase MCP’s lethal trifecta”: simonwillison.net

Internal

• Supabase MCP server in the catalog
• Database MCP servers
• What is the Model Context Protocol?
• Browse all MCP servers