Supabase MCP Server Setup: Read-Only and Project Scope
On this page
What it's good for, and the risk
Connected to Supabase, an agent can create a table, write the migration, generate TypeScript types and check the advisors for missing indexes or row level security gaps. That's a big speed-up when you're building.
It's also a database connection driven by a language model. Supabase's own docs warn that production projects can contain sensitive data and that prompt injection is a risk. So this guide sets up the safe version first, and shows how to open it up when you need more.
Step 1: build your URL
The hosted server lives at https://mcp.supabase.com/mcp. Query parameters control what it can do:
| Parameter | Effect |
|---|---|
project_ref=<id> | Limits the server to one project and hides account-wide tools |
read_only=true | Runs every query as a read-only Postgres user |
features=database,docs | Turns on only the listed tool groups |
Find your project ref in the project's URL in the Supabase dashboard. A safe starting point for a project with real data looks like this:
https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=trueFor a throwaway development project, you can drop read_only so the agent can apply migrations.
Step 2: add it to your tool
The hosted server signs you in with OAuth, so you don't need a personal access token. The first time the server is used, a browser window asks you to log in and pick the organization that holds your project.
Claude Code (project scope, so the team shares it):
claude mcp add --scope project --transport http supabase \
"https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"Then start Claude Code, run /mcp, select supabase and choose Authenticate. Keep the quotes around the URL: without them, your shell treats & as "run in the background".
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"supabase": {
"url": "https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"
}
}
}VS Code (.vscode/mcp.json):
{
"servers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"
}
}
}Codex CLI starts the OAuth sign-in as soon as you add it:
codex mcp add supabase --url "https://mcp.supabase.com/mcp?project_ref=abcdefghijklmnop&read_only=true"What the agent can do
Tools come in groups. The ones you'll use most:
- Database:
list_tables,list_extensions,list_migrations,apply_migration,execute_sql - Debugging:
query_logs,get_advisors(security and performance advice) - Development:
get_project_url,get_publishable_keys,generate_typescript_types - Docs:
search_docs, for questions about Supabase itself
There are also groups for Edge Functions, branching (experimental, paid plans) and storage, which is off by default. Account management tools disappear when you set project_ref, which is one more reason to set it.
Rules for using it safely
Supabase's documentation is direct about this, and the advice is good:
- Use it as a developer tool. Don't connect it to an app your customers use.
- Prefer a development project. Connect to production only when the task needs production evidence, and then with
project_refandread_only=true. - Keep manual approval on. Read each
execute_sqlandapply_migrationcall before you approve it. Data in your tables can contain text that tries to instruct the agent, and approval is your chance to catch it. - For unattended runs, such as a CI job, pre-approve only the project-scoped, read-only tools that job needs. CI can't do the browser sign-in, so it uses a personal access token in an
Authorization: Bearerheader instead.
http://localhost:54321/mcp. It has fewer tools and no OAuth, which is fine for local experiments.Check it works
Ask: "List the tables in my Supabase project and how many rows each has." You should see list_tables, maybe followed by execute_sql with a count query. If you set read_only=true, try "drop the todos table" in a test project. The call should fail, which proves the guard is working.
Check yourself
project_ref for that one project and read_only=true. Optionally add features= with only the tool groups you need.
The URL contains &, which the shell would otherwise treat as an operator and cut the URL short.
Don't. Supabase recommends it only as an internal developer tool, because of the data access and prompt injection risk.