Build my server

Guides

Supabase MCP Server: Setup, Scoping and Security (Oct 2026)

By Team TrustedMCP

On this page
Supabase MCP Server: Setup, Scoping and Security (Oct 2026)

The Supabase MCP server is Supabase's own hosted server at https://mcp.supabase.com/mcp. It lets an agent manage projects, run SQL and inspect your schema. TrustedMCP grades it A. One caution first: scope it with project_ref and read_only=true, and keep it off production data.

The source is open at supabase/mcp. You sign in with OAuth in the browser, so there is no key to paste for normal use.

What it connects

Tools come in feature groups. Supabase's docs list these:

  • database: list tables, extensions and migrations, apply a migration, run SQL.
  • debugging: query logs and get security and performance advisors.
  • development: project URL, publishable keys, TypeScript types.
  • functions: list, read and deploy Edge Functions.
  • account: list, create, pause and restore projects. Off when you set project_ref.
  • docs: search the Supabase docs.
  • branching: create, merge, reset and delete branches. Paid plans only.
  • storage: buckets and storage config. The only group off by default.

Setup

The snippets below come from Supabase's MCP docs and the README. Replace <project-ref> with your project's ref. All of them use the hardened URL from the next section.

Claude Code (writes to .mcp.json in your project):

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

Then sign in. Supabase says to run this in a regular terminal, not the IDE extension, and pick "supabase" then "Authenticate":

claude /mcp

Cursor (.cursor/mcp.json, or ~/.cursor/mcp.json for all projects):

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

VS Code (.vscode/mcp.json):

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

Other clients (Codex, Gemini CLI, Windsurf, Claude.ai, ChatGPT and more) are in the docs' config panel. The README says most clients take the same type and url pair. The Supabase dashboard can also build your URL for you.

On first use, a browser window opens for Supabase sign-in. Choose the organization that holds your project.

Scope it before you connect

With a bare https://mcp.supabase.com/mcp, the agent can reach every project in the organization you approve, with write access. Four settings fix that:

  • project_ref=<id> locks the server to one project. It also removes the account tools, so the agent can't list or create other projects.
  • read_only=true runs every query as a read-only Postgres user.
  • features=database,docs loads only the groups you name. Fewer tools means a smaller attack surface.
  • Use a dev project or a branch, not production. Supabase suggests branching to test changes away from live data.

Supabase's docs are frank about the risk. They call prompt injection "the primary attack vector unique to LLMs". Their example is a support ticket whose text says to select * from <sensitive table> and post the result as a reply. When a developer asks the agent to read that ticket, the agent may run the query.

Supabase wraps SQL results with extra instructions that tell the model to ignore commands inside the data. The docs say "this is not foolproof though, so you should always review the output before proceeding with further actions."

Keep manual approval on. The docs say: "Keep manual approval enabled for interactive work, and review each tool call before you run it." Some clients also show a confirm dialog for destructive SQL and for actions that cost money. Supabase calls these "a guardrail", not a guarantee.

Security notes

Production is your call, so make it a careful one. Our advice is to keep this server away from production data. Supabase's docs say to connect to production "only when the task requires production evidence", and then with project scoping, read-only mode and fewer feature groups.

Don't hand it to customers. The server runs with your developer permissions. Supabase says to use it as an internal developer tool only.

PATs are for CI only. The default login is OAuth with dynamic client registration, so you don't need a personal access token. The docs suggest a PAT only where a browser login is impossible, such as CI. Then you send it in an Authorization header, scope it to one project and grant only the permissions your tools need. Keep the token in a CI secret, never in a committed file.

Local development. If you run Supabase locally with the CLI, the server is at http://localhost:54321/mcp. Supabase says it has "a limited subset of tools and no OAuth 2.1" there. That's fine for a local stack with fake data.

More in MCP security best practices and is it safe to install an MCP server.

Why it grades A

  • Maintenance, 25 of 25. Active repo in Supabase's own GitHub org.
  • Known CVEs, 25 of 25. No published advisories.
  • Transport, 20 of 20. Hosted over HTTPS.
  • Authentication, 18 of 30. This is the only deduction. OAuth 2.1 is the default, which is good. But one sign-in grants access to the whole organization, with all scopes. Supabase's docs say fine-grained scopes are not available yet. Project scoping and read-only mode exist, but you must opt in by adding them to the URL.

Full breakdown on the Supabase MCP listing. The method is in how TrustedMCP scores servers. Similar servers are under databases.

FAQs

How do I install Supabase MCP in Claude Code or Cursor? Use the snippets above. In Claude Code, run claude mcp add, then claude /mcp to sign in. In Cursor, add the JSON to .cursor/mcp.json and sign in when asked. Check it under Settings > Cursor Settings > Tools & MCP.

Do I need an access token? No, not for normal use. OAuth sign-in happens in the browser. Use a personal access token only in CI or other places where a browser login can't run.

Why does it show 0 tools? Supabase notes that some clients need a restart after sign-in to detect all tools. Also check that you finished the sign-in (claude /mcp in Claude Code) and picked the organization that holds your project. If you set features=, only those groups load.

Can I make it read-only? Yes. Add read_only=true to the URL. Queries then run as a read-only Postgres user.

Is it safe? Can it touch production? It can touch anything your sign-in can reach, production included. Scope it to one non-production project, turn on read-only mode, and approve each tool call yourself.

Can I use it with the local Supabase CLI? Yes, at http://localhost:54321/mcp. It has fewer tools and no OAuth.

Does it use a lot of context? Every enabled tool's description loads into context. features= cuts the tool list down, and project_ref drops the account tools. See why MCP servers eat your context window.