Supabase MCP: Setup, Read-Only Mode and the Risks

Supabase MCP is Supabase’s own hosted MCP server at https://mcp.supabase.com/mcp. You add that URL to Claude Code, Cursor, VS Code or any client that speaks MCP over HTTP, and the first connection sends you to a browser to sign in to Supabase and grant the client access. There is no key to paste. Three query parameters then decide what the assistant can reach: project_ref locks it to one project, read_only=true makes every query run as a read-only Postgres user, and features loads only the tool groups you name. Use all three unless you have a reason not to.

This piece is about Supabase’s server in particular. The general rules for letting any assistant near a database, from read-only logins and column grants to replicas and what never to connect, are in database MCP servers, and are not repeated here.

The URL and its three switches

Supabase’s MCP guide↗ (opens in a new tab) documents the parameters, and they combine in one address:

https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs,debugging

• project_ref=<id> scopes the server to a single project and switches off the account management tools, so the assistant cannot list, create or pause your other projects.
• read_only=true runs every query as a read-only Postgres user. The server’s code also leaves out the tools that change things when this is set.
• features=<groups> loads only the tool groups you list, separated by commas. Fewer tools means a shorter list for the model to choose from and less that can go wrong.

The tool groups

Supabase groups its tools, and most groups are on unless you narrow them with features:

• Database: list_tables, list_extensions, list_migrations, apply_migration and execute_sql. The last two are the ones that can change your schema and data.
• Debugging: query_logs, a read-only SQL query over project logs, and get_advisors, which returns Supabase’s security and performance advisors.
• Development: get_project_url, get_publishable_keys and generate_typescript_types.
• Edge Functions: list and read functions, and deploy_edge_function, which ships code.
• Docs: search_docs, which searches Supabase’s documentation and touches nothing of yours.
• Branching: create, list, merge, reset, rebase and delete development branches. Supabase marks it experimental, and branching needs a paid plan.
• Storage: buckets and storage configuration. This group is off by default.
• Account management: projects, organisations and costs. Hidden when project_ref is set.

For an assistant helping you write queries and types, database,docs,debugging,development in read-only mode is enough. Leave Edge Functions and Branching out until a task needs them.

Setup in Claude Code

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

Then type /mcp inside Claude Code, choose supabase and authenticate; the browser does the rest. --scope project writes the entry to .mcp.json at the repository root, so everyone who clones the repository gets the same scoped, read-only server and signs in as themselves. Keep the quotes around the URL, or your shell will treat the & as a command separator. The --scope and --transport options are described in Claude Code’s MCP documentation↗ (opens in a new tab).

Setup in Cursor

Add the entry to .cursor/mcp.json for one project or ~/.cursor/mcp.json for all of them. Cursor shows a prompt to connect and runs the sign-in. The file holds no secret, only an address, so it is safe to commit.

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

Setup in VS Code

VS Code reads .vscode/mcp.json, which uses a top-level servers object rather than mcpServers. Start the server from the file or the MCP view and sign in when asked.

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

One catch: VS Code now runs chat through agent harnesses, and its agent harness guide↗ (opens in a new tab) says Copilot sessions can currently reach only local MCP servers that need no authentication. Supabase’s hosted server signs you in, so use a Local session for it. How VS Code stores and trusts the entry is in VS Code MCP security, and the file itself in the VS Code mcp.json guide.

When OAuth is not an option

• CI and headless clients: create a personal access token under your Supabase account’s access tokens, named for its purpose. Supabase says to scope it to the project the server connects to and grant only the permissions your enabled tools need, then send it as an Authorization: Bearer header. Keep project_ref and read_only=true on the URL all the same, and keep the token in your secret store rather than the config file.
• Clients that need a client ID and secret: add an OAuth app under your Supabase organisation, using the website and callback addresses the client expects, then copy its client ID and secret into the client.
• Local development: the Supabase CLI serves an MCP endpoint at http://localhost:54321/mcp for your local stack. The supabase-mcp repository↗ (opens in a new tab) notes that the CLI and self-hosted versions offer a limited subset of tools and no OAuth 2.1.

The warnings Supabase gives

Supabase is unusually direct about the risks of its own server, and its advice is worth reading as a checklist:

1. Protect production data. Connect to a production project only when the task needs production evidence, and then with project scoping, read-only mode and restricted feature groups.
2. Do not give it to your customers. The server acts with your developer permissions, so it belongs in your tools, never in an assistant your end users talk to.
3. Use a branch. Supabase points to its branching feature for a development copy the assistant can change without harm.
4. Keep manual approval on. Most clients ask before each tool call; leave that on for interactive work and read each call, especially execute_sql and apply_migration.
5. Pre-approve only what an unattended routine needs. A scheduled job cannot ask you mid-run, so approve in advance only the project-scoped, read-only tools it uses.

The reason behind all five is prompt injection. Supabase’s example is a support ticket whose text tells the assistant to run a query and reveal the results. The server wraps SQL results with extra instructions that discourage the model from obeying anything inside the data, and Supabase is clear that this lowers the risk rather than removing it. A session that can read customer rows and also write, send or publish is the dangerous combination, set out in full in indirect prompt injection.

A sensible starting set-up

• Point it at a development project or branch, never the production project, for day-to-day work.
• Add project_ref, read_only=true and a short features list to the URL, and commit that URL so nobody connects the wide-open version by accident.
• Keep approval prompts on for execute_sql, and let the assistant draft migrations as files for review rather than apply them.
• Behind the server, give the database the narrow login described in database MCP servers, so row-level security and grants hold even if a switch is left off.

Where the findings go

An assistant with get_advisors will find things: security and performance advice about your project that someone has to act on. Those are work, and they belong on a board rather than in a chat that scrolls away. On fenbs, the same client that holds the Supabase server can connect to https://fenbs.ai/api/mcp and file each finding as a bug or an enhancement with a priority from 1 to 10, a note saying what and where, and a plan once somebody knows the fix. The connection signs in with OAuth and gets an hour-long token with refresh, capped by the read, write and comment scopes you tick and by your role on the board, and History records each change under the assistant’s name. fenbs does not connect to Supabase itself; the assistant carries the finding across.