Guide
Supabase MCP Server: Setup, Read-Only Mode and Safe Agent Access
Connect the official Supabase MCP server to your AI coding tool, lock it to one project in read-only mode, and know when agents need a governed data layer instead.
By the Agentic Infrastructure Review editors · Updated
The Supabase MCP server is how an AI agent gets into your Supabase project. It is the official Model Context Protocol server Supabase runs, and once it is connected, a coding agent such as Claude Code, Cursor or Codex can list your tables, run SQL, apply migrations and read your logs for you. You can set it up in a couple of minutes. Deciding how much access the agent should have takes longer, and that is what most of this guide covers.
The steps, configuration and tool names below follow Supabase's own documentation as of November 2026. The server changes often, so check there before you rely on a specific flag.
What the Supabase MCP server is
- Hosted, not installed. The server runs at
https://mcp.supabase.com/mcp. If you develop locally with the Supabase CLI, the same server is athttp://localhost:54321/mcp. - It signs in with OAuth. On first use, your client opens a browser window where you sign in to Supabase and pick the organization to grant access to. Interactive use doesn't need a personal access token (PAT).
- It acts as you. Every tool call runs with your developer permissions. That is why Supabase says not to give it to customers or end users.
- Open source. The code is at github.com/supabase/mcp.
How to connect it to your AI tool
The basic setup is the same in every client: add a server named supabase that points at the hosted URL, then sign in. Here are the four most common clients. Supabase's docs list many more, including Gemini CLI, GitHub Copilot, OpenCode, Kiro, Goose and the Claude.ai and ChatGPT connectors.
Claude Code
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"
Or put it in .mcp.json at the project root:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}
Then authenticate from a regular terminal, not the IDE extension: run claude /mcp, select supabase, and choose Authenticate.
Cursor
Add this to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json to make it available in every project:
{
"mcpServers": {
"supabase": {
"url": "https://mcp.supabase.com/mcp"
}
}
}
Cursor opens the sign-in flow after you add it. You can confirm the connection under Settings → Cursor Settings → Tools & MCP. The Cursor CLI uses the same file: agent mcp enable supabase, then agent mcp login supabase.
Codex
codex mcp add supabase --url "https://mcp.supabase.com/mcp"
codex mcp login supabase
Or add it to ~/.codex/config.toml:
[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp"
Run /mcp inside Codex to check that it is authenticated.
VS Code
Add this to .vscode/mcp.json:
{
"servers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}
To check the connection in any client, ask it something like "What tables are there in the database? Use MCP tools." Some clients need a restart after you sign in before they show all the tools.
Scope it before you connect it
The URLs above give the agent every project in the organization you signed in to, along with write access. Before you point it at anything real, narrow it with URL query parameters:
| Parameter | What it does | Example |
|---|---|---|
project_ref=<id> |
Limits the server to one project and turns off the account tools | ?project_ref=abc123 |
read_only=true |
Runs every query as a read-only Postgres user | ?read_only=true |
features=<groups> |
Enables only the tool groups you list | ?features=database,docs |
skip_elicitations=<tools> |
Skips the server's confirmation forms for the tools you name | ?skip_elicitations=execute_sql |
You can combine them. For an agent that should read schema and data in a single project and nothing else, this is a sensible starting point:
https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true&features=database,docs
Your project ref is the ID in your project's dashboard URL and API URL. Leave skip_elicitations out unless you have a specific reason to use it. The confirmation forms are one of the few checks between the agent and a destructive statement.
What the agent can do once connected
Tools come in feature groups. All groups your connection supports are on by default except Storage.
- Database:
list_tables,list_extensions,list_migrations,apply_migration,execute_sql. - Debugging:
query_logs(read-only SQL over project logs) andget_advisors(security and performance advisors). - Development:
get_project_url,get_publishable_keys,generate_typescript_types. - Edge Functions: list, get and deploy functions, plus a secret-entry flow that keeps secret values in the dashboard, out of chat.
- Account management: list, create, pause and restore projects, and read organizations. These tools are switched off when you set
project_ref. - Docs:
search_docsover the Supabase documentation. - Branching (experimental, paid plans): create, list, delete, merge, reset and rebase branches.
- Notebooks (hosted connections only), Storage (off by default) and Feedback (off in read-only mode).
execute_sql is the tool that matters most. With it, the agent can run whatever SQL it writes against your database.
What read-only mode does and does not protect
read_only=true runs queries as a read-only Postgres user, so the agent can't insert, update, drop or migrate anything. It does not decide what the agent can read. If that user can see a table of customer emails, so can the agent.
The bigger risk is prompt injection. Supabase's docs give this example: a customer submits a support ticket containing instructions to select * from a sensitive table and post the result as a reply. Later, a developer asks their agent to read the ticket through MCP, and the agent follows the instructions hidden in the data. Supabase wraps SQL results in extra instructions that tell the model not to obey anything inside them, but says plainly that this is not foolproof. We cover the general version of this attack in Prompt Injection via Untrusted Database Results.
Supabase recommends these practices, and so do we:
- Keep manual approval on. Most clients ask before each tool call. For interactive work, read each call before you approve it.
- Use a development branch or a non-production project for anything that writes. Connect to production only when the task needs production evidence.
- Scope to one project, in read-only mode, with only the groups you need. Unattended routines in particular should be read-only and should report a recommendation rather than run a write.
- Don't put secrets or unrelated personal data into prompts.
- Don't ship it to customers. It holds your developer permissions.
Using it in CI or another headless environment
Where a browser sign-in isn't possible, create a personal access token in your Supabase account settings. Scope it to the one project and give it only the permissions your enabled tools need. Then pass it as a header. With Claude Code, for example:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}&read_only=true",
"headers": {
"Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
}
}
}
}
Keep the token in your CI secret store, never in the repository. Not every MCP client supports custom headers, so check yours before you plan around this.
Where the Supabase MCP server stops being the right tool
The Supabase MCP server is built for development work: designing schemas, writing migrations, debugging and generating types. Using it for analytics, so an agent can answer "what was our MRR last month?", runs into three problems:
- It queries the live database. Every analytical question becomes a query against the Postgres instance that serves your users. An agent scanning a large events table competes with your app for the same resources. See Production Database Access Risks for AI Agents.
- Each agent writes its own SQL. Two agents, or the same agent on two days, can define "active user" or "MRR" differently and both return confident numbers. Read-only mode does nothing about that. See AI Agents That Compute Their Own Metrics Are Governance Failures.
- Access is all or nothing at the table level. The agent sees whatever its Postgres role sees. It can't be limited to a list of approved metrics.
For recurring metrics, board numbers and agents that run without a person watching, the safer pattern is a governed layer between production and the agent. Metrics are defined once and pre-calculated, the data is copied away from the production instance, and agents get MCP access to that layer instead of the raw schema. MCP Server Architecture Patterns That Turn a Supabase Schema Into a Live Agent-Queryable Analytics Endpoint walks through the design, and Choosing an Analytics Layer When Your Entire Stack Is Already Supabase compares ways to build it. Dreambase, for example, pre-models a Supabase project's data into governed Parquet datasets that agents query through DuckDB and a single MCP server, so they never touch the production database. Check each vendor's own site for current features and pricing.
A practical split: give developers the Supabase MCP server, scoped and read-only, for building the product. Give analytics agents a governed layer for answering questions about the business.
Frequently asked questions
- What is the Supabase MCP server?
- It is Supabase's official Model Context Protocol server. It lets an AI client such as Claude Code, Cursor, Codex or VS Code list your tables, run SQL, apply migrations, read logs and advisors, deploy Edge Functions and search the Supabase docs, using your own Supabase permissions.
- What is the Supabase MCP server URL?
- The hosted server is https://mcp.supabase.com/mcp. When you develop locally with the Supabase CLI, it is http://localhost:54321/mcp instead.
- Do I need a personal access token?
- Not for interactive use. The hosted server signs you in through the browser with OAuth. A personal access token passed in an Authorization header is only needed where a browser sign-in is impossible, such as CI.
- How do I make the Supabase MCP server read-only?
- Add read_only=true to the server URL, for example https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true. SQL then runs as a read-only Postgres user. It still lets the agent read every table that user can see.
- Should I connect the Supabase MCP server to my production database?
- Supabase advises connecting to production only when a task needs production evidence, and then scoped to that one project, in read-only mode, with only the tool groups you need. For recurring metrics and agent workflows, serve agents a governed copy of the data rather than the live database.
- Can I give the Supabase MCP server to my customers?
- No. It acts with your developer permissions, so Supabase says to use it internally as a developer tool, not to hand it to customers or end users.
- Is the Supabase MCP server free?
- Supabase's docs don't put a price on the server itself, but some tools act on paid resources. Creating a project or a branch can cost money (the server asks you to confirm), and branching needs a paid plan. Check supabase.com/pricing for current plans.





