How to set up the Supabase MCP server in Claude Code, Cursor, Codex and VS Code
Checked against the official docs:
The Supabase MCP server lets an AI agent work with your Supabase projects: list and change tables, run SQL, apply migrations, read logs, deploy Edge Functions and search the Supabase docs. Supabase hosts it, and you sign in with your Supabase account, so there is no key to copy. Because it touches a real database, this guide starts with the settings that keep it safe, then covers each client, local development, CI and troubleshooting. It's based on Supabase's MCP docs and the supabase-community/supabase-mcp README (checked 18 November 2026).
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.
Quick answer
- Server URL:
https://mcp.supabase.com/mcp. Your client opens a browser sign-in to Supabase; pick the organization that has your project. No personal access token needed. - Safer URL for everyday use:
https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=truelimits the agent to one project and read-only queries. - Claude Code:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp", then authenticate from/mcp. - Local development: with the Supabase CLI running, use
http://localhost:54321/mcp(fewer tools, no sign-in).
Free: MCP Starter Checklist
One page: Inspector smoke-test, Claude Code + Cursor connect steps, and the stdout gotcha. Join the list and download it free.
Read this first: the risks
Supabase's docs are direct about it: connecting an AI model to your database carries real risk. The main one is prompt injection. Their example: a customer writes a support ticket containing instructions to select data from a sensitive table and post it as a reply. When a developer asks their agent to read that ticket through Supabase MCP, the agent may try to follow those instructions with the developer's permissions.
What Supabase recommends:
- Don't connect to production unless the task really needs production data. Use a development project, or a development branch with Supabase branching.
- Scope to one project with
project_ref, so the agent can't reach other projects in your account. - Use read-only mode (
read_only=true), which runs every query as a read-only Postgres user. - Enable only the tool groups you need with the
featuresoption. - Keep manual approval on in your client, and review each tool call before it runs.
- Don't give it to your customers. The server runs with your developer permissions; it's a tool for building and testing, not for end users.
For a shorter overview, see the Supabase MCP listing.
Build your server URL
Every option is a query parameter on the URL. You can combine them:
project_ref=<id>: limit the server to one project. This also turns off account-level tools such as listing and creating projects.read_only=true: run all queries as a read-only Postgres user.features=database,docs: enable only the listed tool groups (comma-separated).skip_elicitations=<tools>: skip specific confirmation forms. Leave this out unless you have a reason; it removes a safety prompt.
https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docsYou can also generate the URL for your project in the MCP tab of the Connect panel in the Supabase dashboard. Quote the URL in terminal commands, because ? and & mean something to your shell.
Claude Code
Add the server to your project config:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"That writes a .mcp.json file in the project, which you can also create by hand:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}Then authenticate. Supabase says to do this in a regular terminal, not the IDE extension: start Claude Code, run /mcp, select supabase, then Authenticate. If Claude Code keeps reporting that the server needs authentication, see fix Claude Code MCP "needs authentication".
The Supabase plugin (MCP server plus skills)
Supabase also offers a plugin that installs the MCP server together with its agent skills (Supabase guidance and Postgres best practices). It detects your installed coding agents and installs into each:
npx plugins add supabase-community/supabase-pluginCodex
codex mcp add supabase --url "https://mcp.supabase.com/mcp"
codex mcp login supabaseOr add the server to ~/.codex/config.toml yourself, then run the login command:
[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp"Run /mcp inside Codex to confirm you are signed in. More on Codex config: how to add an MCP server to Codex.
Cursor
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it in every project:
{
"mcpServers": {
"supabase": {
"url": "https://mcp.supabase.com/mcp"
}
}
}After you sign in, check the connection under Settings → Cursor Settings → Tools & MCP. The Cursor CLI uses the same config; there you approve and sign in with:
agent mcp enable supabase
agent mcp login supabase
agent mcp listDetails on file locations: how to add an MCP server to Cursor.
VS Code
Add this to .vscode/mcp.json in your project:
{
"servers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}VS Code uses servers, not mcpServers; see how to add an MCP server to VS Code.
Claude.ai, ChatGPT and other clients
- Claude.ai and ChatGPT: Supabase is available as a connector in each app's directory; install it from there.
- Gemini CLI (version 0.20.2 or later):
gemini mcp add -t http supabase "https://mcp.supabase.com/mcp", then run/mcp auth supabaseinside Gemini CLI. Supabase also has a Gemini CLI extension that bundles the server and skills. - Antigravity: add the URL under
serverUrlin~/.gemini/antigravity/mcp_config.json, restart, and complete the sign-in. - Anything else: copy the standard block (
"type": "http"and the URL) into the format your client expects.
What the tools can do
Tools come in feature groups. All groups your connection supports are on by default, except Storage:
- Database: list tables, extensions and migrations; apply migrations; run SQL (
execute_sql). - Debugging: query project logs with read-only SQL; get security and performance advisors.
- Development: get the project API URL and publishable keys; generate TypeScript types from your schema.
- Edge Functions: list, read and deploy functions.
- Account management: list, create, pause and restore projects; organizations; cost checks. Turned off when you use
project_ref. - Docs: search the Supabase documentation.
- Branching (experimental, needs a paid plan): create, merge, reset and delete development branches.
- Storage (off by default): list buckets and read or change storage settings.
- Notebooks (hosted connections only): list, create and run project notebooks.
Confirmations before risky actions
If your client supports MCP form prompts (called elicitation), the server pauses and asks you before some actions: it shows the cost before creating a project or branch, and asks before execute_sql or apply_migration runs SQL it detects as destructive. Supabase calls these a guardrail, not a guarantee: they may not catch every destructive statement, and some clients answer them automatically. Without form support, SQL runs without the extra prompt, so keep your client's own approval step on.
Local development and self-hosting
With the Supabase CLI running a local stack, the server is at http://localhost:54321/mcp. It offers fewer tools than the hosted server and has no OAuth sign-in. If you turned on the experimental multi-project setting, local projects use other ports, so read the MCP URL from supabase status. Self-hosted Supabase also has an MCP server with a limited tool set; Supabase's self-hosting docs explain how to enable it.
CI and other places without a browser
In CI, the browser sign-in isn't possible. Create a personal access token in your Supabase account, scoped to the one project and only the permissions your tools need, and pass it in an Authorization header. Supabase's example for Claude Code reads both values from environment variables:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}",
"headers": {
"Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
}
}
}
}Not every client supports custom headers, so check yours. For unattended jobs, Supabase advises approving only the project-scoped, read-only tools the job needs.
Check that it works
After signing in, restart the client if the tools don't appear, then ask (this is Supabase's own test prompt):
What tables are there in the database? Use MCP tools.The agent should call a Supabase tool such as list_tables. If it answers without calling a tool, check that the server shows as connected in your client's MCP list.
Troubleshooting
- The project you want isn't there: you probably picked a different organization during sign-in. Clear the server's authentication in your client and sign in again, choosing the organization that owns the project.
- Tools don't appear after signing in: restart the client. Some clients only load the tool list after authorization.
- Writes or migrations fail: check for
read_only=truein the URL. That's expected in read-only mode. - Project tools like list_projects are missing:
project_refturns off account-level tools by design. - Storage or branching tools are missing: Storage is off by default (turn it on in the configuration panel), and branching needs a paid plan.
- Fewer tools than expected locally: the Supabase CLI server only has a subset of tools.
- No confirmation dialog appears: your client may not support MCP form prompts. Supabase has troubleshooting articles for missing SQL and cost confirmations.
FAQ
Do I need a Supabase access token?
No, not for normal use. The hosted server signs you in through the browser. You only need a personal access token for CI or other places where a browser sign-in isn't possible.
Is it safe to use on my production database?
Supabase recommends against it unless the task really needs production data. If you must, scope the URL to that project, use read-only mode, limit the feature groups and keep manual approval on.
Can my app's users use this MCP server?
No. It runs with your developer permissions. To give your own users an MCP server, Supabase has a separate guide on building and deploying your own.
What other database MCP servers are on PluginStack?
See the Neon MCP server for Neon Postgres, or the best MCP servers for Claude Code for a wider list.
Sources
Commands and config above come from these official docs. Tools change often, so check them for the latest steps.
- Supabase docs: Supabase MCP Server (setup, tools, options, security)
- Supabase docs: Supabase Plugin for AI Coding Agents
- supabase-community/supabase-mcp on GitHub
- Claude Code docs: Connect Claude Code to tools via MCP
- OpenAI Codex docs: Model Context Protocol
PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.
Related guides
Tools in this guide
Get new guides by email
New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.