Est.

Guide

Supabase MCP: What the Server Exposes and How to Scope It for AI Agents

A guide to the Supabase MCP server: its tool groups, the read_only, project_ref and features settings, and how to keep AI agents away from production data.

Agent Data Digest · Updated , checked against the sources listed at the end

What Supabase MCP is

Supabase MCP is Supabase's own Model Context Protocol server. Connected to an AI client such as Claude Code, Cursor, Codex or VS Code, it lets the agent list your tables, run SQL, apply migrations, read logs, deploy Edge Functions and manage projects and branches, all on your behalf.

The hosted server lives at https://mcp.supabase.com/mcp. When you develop locally with the Supabase CLI, the same server is at http://localhost:54321/mcp. Its source is public at github.com/supabase/mcp.

The one fact that shapes everything else on this page: the server acts with your developer permissions. Whatever you can do to a project in the Supabase Dashboard, an agent connected through Supabase MCP can attempt, unless you narrow it with the settings below.

Connecting it to an AI client

Most clients take the server's URL in their MCP config and then open a browser window to sign in. The hosted server uses OAuth with dynamic client registration, so you choose the Supabase organization to grant and don't need to create a personal access token. In Cursor, for example, .cursor/mcp.json holds:

{
  "mcpServers": {
    "supabase": {
      "url": "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true&features=database,docs"
    }
  }
}

Claude Code adds the same server from the command line, and you authenticate by running /mcp in a regular terminal:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"

The exact file and command differ by client and change often. Supabase keeps the current instructions for each client on its MCP docs page, with a panel that builds the URL for you.

Where a browser sign-in is impossible, as in CI, Supabase documents passing a personal access token in an Authorization: Bearer header instead. Scope that token to the one project and to the permissions your enabled tools need, and keep it in the CI's secrets, never in the config file.

The tools it gives an agent

Tools come in feature groups. Every group your connection supports is on by default except Storage, so an unscoped connection hands the agent most of this table:

GroupToolsWhat an agent can do with it
Databaselist_tables, list_extensions, list_migrations, apply_migration, execute_sqlRead the schema, run any SQL your role allows, change the schema
Debuggingquery_logs, get_advisorsQuery project logs with read-only SQL; read security and performance advisors
Developmentget_project_url, get_publishable_keys, generate_typescript_typesFetch the API URL and publishable keys; generate types from the schema
Edge Functionslist_edge_functions, get_edge_function, deploy_edge_function, create_edge_function_secretRead and deploy server code; request a secret be entered in the Dashboard
Accountlist_projects, get_project, create_project, pause_project, restore_project, list_organizations, get_organization, get_cost, confirm_costSee every project you can reach; create, pause and restore them
Docssearch_docsSearch Supabase's documentation
Branching (experimental)create_branch, list_branches, delete_branch, merge_branch, reset_branch, rebase_branchMake and merge database branches (needs a paid plan)
Storage (off by default)list_storage_buckets, get_storage_config, update_storage_configRead and change storage settings
Notebooks (hosted only)list_notebooks, get_notebook, create_notebook, run_notebook, delete_notebookRun SQL cells your team saved in notebooks, even with Database turned off
Feedbacksubmit_feedback, delete_feedbackSend feedback to Supabase (off in read-only mode)

Supabase adds and renames tools over time. Before you rely on this list, ask your client to list the Supabase tools it actually sees, or check the docs.

The three settings that decide the blast radius

Supabase MCP is configured with query parameters on its URL. Three of them decide how much damage a confused or manipulated agent can do:

ParameterWhat it doesExample
project_refLimits the server to one project and turns off the account tools, so the agent can't see or touch your other projects?project_ref=abc123
read_onlyRuns every query as a read-only Postgres user?read_only=true
featuresTurns on only the tool groups you name?features=database,docs

They combine: https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true&features=database,debugging is a server that can read one project's data and logs and nothing else. Start there and add groups only when a task needs them.

A fourth parameter, skip_elicitations, works in the other direction: it turns off the confirmation forms described below for the tools you name. It never bypasses authentication, permissions or read-only mode, but it does remove a check, so leave it out unless you know why you need it.

Confirmations are a guardrail, not a review

When your client supports MCP elicitation, the server pauses some calls to ask you first: create_project and create_branch show their cost, execute_sql and apply_migration ask before SQL they detect as destructive, and run_notebook and delete_notebook ask before writes and deletions.

Supabase is plain about the limits. The destructive-SQL check may not catch every destructive statement, some clients can answer these prompts automatically through hooks or rules, and where a client doesn't support forms, SQL runs without the extra prompt. Treat a confirmation as one more chance to catch a mistake, and keep your client's own per-call approval switched on as well.

The risk that comes with your data: prompt injection

An agent reading your tables also reads whatever your users wrote into them. Supabase's own example is a support-ticket app: a customer files a ticket that says to ignore previous instructions, select from a sensitive table and post the result as a reply. A developer later asks their agent to read the ticket through Supabase MCP, and the agent, running with that developer's permissions, tries to do it.

Supabase MCP wraps SQL results in extra instructions that tell the model not to follow commands found in the data, and Supabase says itself that this is not foolproof. What actually limits the damage is what the connection can do when the model does follow them: read-only mode, one project, few tool groups, and a person approving each call. Our piece on prompt injection in data-reading agents goes further into the pattern.

Which setup fits which job

JobConnect toSettingsAlso
Building features and migrations with a coding agentA development project or a database branch, never productionproject_ref of that project; features=database,development,docs plus what the task needsApprove each tool call; merge schema changes through your normal review
Debugging an issue in productionProduction, only when the task needs production evidenceproject_ref, read_only=true, features=database,debuggingAsk the narrowest query that answers the question; keep secrets and unrelated personal data out of prompts
An unattended monitoring routineThe one project it watchesproject_ref, read_only=true, the fewest groups that workPre-approve only read-only tools; have it stop and report rather than write
An agent your customers or teammates ask business questionsNot Supabase MCPNone of these settings fix it: the server runs with a developer's permissionsGive the agent governed, pre-defined metrics instead (see below)

Supabase's guidance on the last row is direct: don't give the MCP server to your customers or end users. It is a developer tool for building and testing your application.

Where Supabase MCP stops

Even scoped and read-only, Supabase MCP gives an agent raw tables and free-form SQL. That suits a developer who knows the schema and reads each query. It suits an agent answering "what was churn last month?" much less well: two runs can join the tables differently and return two numbers, every question costs a fresh scan of your operational database, and nothing records which definition of churn the answer used.

For agents that report numbers rather than build software, the pattern this site keeps coming back to is a separate, governed layer: metrics defined once, calculated ahead of time, and served through tools that take a metric name rather than SQL. The pieces below cover how to build it and why.

Before you connect: a short checklist

  1. Decide which project the agent may touch, and set project_ref to it. Prefer a development project or branch.
  2. Add read_only=true unless the task is to change the schema or deploy code.
  3. List only the tool groups the task needs in features.
  4. Leave skip_elicitations out, and keep your client's per-call approval on.
  5. In CI, use a personal access token scoped to that project, stored as a secret.
  6. Ask the client to list the tools it sees, and check the list matches what you meant to allow.
  7. Re-check the Supabase MCP docs when you upgrade: tools and defaults change.

For judging any MCP server, not only Supabase's, see The MCP Server Evaluation Checklist for Teams Running AI Agents Against Supabase.

Questions people ask

Does Supabase MCP need a personal access token?

Not for the hosted server in a client that can open a browser: it signs you in with OAuth and dynamic client registration. You need a personal access token, passed in an Authorization header, where a browser sign-in isn't possible, such as CI.

Can I use Supabase MCP with a local project?

Yes. With the Supabase CLI running locally, the server is at http://localhost:54321/mcp. The Notebooks tools are only on the hosted server.

Is read-only mode enough to connect Supabase MCP to production?

It stops writes, not reads. An agent in read-only mode can still read any row your role can, including data a prompt injection asks it to surface. Combine it with project_ref, a short features list and manual approval, and connect to production only when the task needs production evidence.

What does Supabase MCP cost?

Supabase's MCP docs don't list a price for the server itself. Tools that create resources, like create_project and create_branch, can add charges and show the cost for you to confirm first, and the branching tools need a paid plan. Check Supabase's pricing page for current numbers.

Sources

  1. Supabase MCP Server - Supabase Docs
  2. supabase/mcp on GitHub
  3. Branching - Supabase Docs
  4. Introduction - Model Context Protocol

Further reading