Skip to content
Agentic Control Plane

The Supabase MCP server control model, explained

The Supabase MCP server is the top-ranked database server in this series. It is first-party (supabase-community/supabase-mcp), and Supabase’s own docs push it into Cursor, Claude Code, and any IDE with an MCP config. You can run it remote (https://mcp.supabase.com/mcp) or local (npx @supabase/mcp-server-supabase).

It ships three controls: read-only, project scoping, and feature groups. They are among the best native controls we’ve surveyed, and one of them enforces at a layer no other server in this series reaches. The docs are also direct about the risks, including a section on prompt injection. Sources: the official docs, the repo README, and the shipped server source.

This page covers the server’s own controls. For the cross-server picture, see the MCP server controls comparison. For what a control layer adds on top, see the coverage matrix.

What’s at stake

This server hands an agent a database, not a repository. The tools include execute_sql (arbitrary SQL against your project), apply_migration (schema changes), deploy_edge_function (code deploy to your edge runtime), create_project and pause/restore at the account level, plus branching and storage writes.

Unscoped and read-write, that is every table in every project in the account, writable by whatever SQL the model decides to write next. Supabase’s guidance opens with two statements that frame the rest of this page. The server is “only designed for development and testing purposes,” and it runs “under the context of your developer permissions.” That is why the docs also say not to hand it to your customers.

Auth: OAuth remote, PAT local

The remote server uses OAuth with dynamic client registration. The client opens a browser login, and the grant currently covers all available scopes. CI and the local server use a personal access token (--access-token or SUPABASE_ACCESS_TOKEN, or an Authorization: Bearer header against the remote).

Unlike GitHub’s fine-grained PATs, a Supabase PAT is account-wide. You can’t scope it to one project or to read-only. So the credential gives you little, and the real narrowing happens in the two flags below, which live in the client config rather than on the credential.

Read-only: enforced at the database, not the tool list

Use --read-only on the local server or ?read_only=true on the remote. It does two things, and the second makes it the strongest single control in this series:

  1. Mutating tools are removed. apply_migration, deploy_edge_function, and the storage and branching writes don’t appear in tools/list.
  2. SQL runs as a read-only Postgres user. The docs say read-only mode “executes all queries as a read-only Postgres user,” and the source forwards the flag to Supabase’s management API on every query. That is enforcement in the database, a level below the tool schema.

GitHub’s read-only is a filter on the tool list and nothing more. Here, even if the tool layer fails, the Postgres role refuses the write. That covers a prompt-injected execute_sql call carrying an UPDATE, a jailbroken argument, or a bug in the filter.

Every control on these pages is graded on whether it still holds when the layer above it fails. This is the one native control in the survey that does. Supabase recommends read-only whenever the server touches real data, and it should be your default.

Project scoping: the blast-radius flag

--project-ref (or ?project_ref=<id>) pins the server to one project and disables the account-level tools. Their project_id inputs disappear from the schemas. Without it, the server works across every project the account can see. The docs say scoping “prevents LLMs from accessing data from other projects in your Supabase account.”

Because the token can’t be narrowed, this flag is the only thing between one agent session and your whole account. It is one line of client config.

Feature groups: subtraction at launch

--features (or ?features=database,docs) picks from eight groups: docs, account, database, debugging, development, functions, branching, and storage. Everything but storage is on by default. Branching is experimental and paid-plan only. account is dropped automatically when the server is project-scoped.

Groups you don’t select don’t exist on the tool list, and the docs recommend restricting them to cut the attack surface. This is the same shape as GitHub’s toolsets: you subtract tools once, at launch. You can remove deploy_edge_function, but you can’t put a condition on it.

Branching: a safety mechanism, not a control

The branching group lets an agent test schema changes on a database branch before anything merges. That is good practice, and Supabase recommends it for that reason. But it changes where changes land, not whether the agent may make them, and the merge tools sit on the same tool list the agent holds. A sandbox the agent can promote out of is a workflow, not a boundary.

The missing pieces: audit, approvals, rate limits

The server writes no record of what an agent ran. There is no MCP-level trail of which tools fired or, more important on a database, what SQL ran, across a session or a fleet. This is the general MCP audit gap in its sharpest form.

There is no approval mechanism. The server can’t hold a call for a human, so the “manual approval” Supabase’s docs lean on means whatever confirmation dialog the client shows. That is a client-side courtesy, and the first thing to vanish in yolo mode.

There are no rate limits. The hundredth execute_sql in a minute looks like the first.

And there is no per-statement policy. Read-only covers the whole session, so “SELECT anywhere, UPDATE only with approval, never DROP” can’t be expressed at any setting of the three controls.

The lethal trifecta incident: what the controls would and wouldn’t have stopped

The Cursor + Supabase exfiltration (our recreation) is the reference incident for this surface. It had untrusted text in a support ticket, an agent with SQL access, and query results flowing back to the attacker’s channel. The incident setup used none of the three controls: unscoped, read-write, service-role-level access.

Read-only plus project scoping would have blocked the write path. The Postgres role refuses the mutation whatever the injected instructions talked the model into attempting. That is real, and more than most servers can say.

But the read-and-exfiltrate path survives read-only entirely. The agent can SELECT the sensitive table and write the result where the attacker reads it. Read-only means the agent can’t corrupt your data. It doesn’t mean the agent can’t leak it.

Supabase knows this. The docs name prompt injection as the main attack vector and describe this support-ticket scenario. They also say the server wraps SQL results with instructions telling the model not to follow embedded text, and they label that “not foolproof.” That candor is to their credit. It also means the defense that remains is a request to the model, not a control on the call.

Models are getting better at refusing this kind of instruction, but a refusal is probabilistic. It is a seatbelt that usually latches, not a lock. Result-wrapping and model skepticism are worth having, and neither should be the only layer on a production database.

Where the native model ends

The read-only role is the strongest single control in the series, and scoping plus feature groups make the recommended setup good. What’s missing has the same shape as on every other server:

  • All three controls are launch flags in the client config. The agent can read that file and can usually write it, and nothing stops a session launching unscoped and read-write “just this once.” The Postgres role holds during a session. Nothing holds the flag that sets it.
  • Nothing is per-statement. One read/write decision per session, no conditions, no holds.
  • Nothing is recorded. No trail of what SQL ran, under which setting, across which projects.
  • The exfiltration path is out of scope by design. A read here plus a write somewhere else is invisible from inside this server, same as GitHub and every other single-server view.

Here is what to do. Never point it at production (their words). Always set --project-ref. Default to --read-only. Trim --features to what the task needs. Leave client approval on.

Then add a layer outside the server config. ACP is one: a hook in the agent’s harness that can hold execute_sql and apply_migration for approval, set a per-minute limit, and record each call. It also blocks the agent’s attempts to write to its own hook files. It decides per tool call, not per SQL statement, and because it runs on the same machine as the agent, it can be disabled there. Keep the read-only role as the backstop.

Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Getting started