Ad space · Your tool here
PluginStack
Setup guide

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.

The newsletter hasn't started sending yet. Join the list now and we'll email you when the first issue goes out. From PluginStack (pluginstackai@gmail.com). Privacy policy.

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=true limits 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.

Markdown download + occasional PluginStack updates. No spam. Privacy policy.

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 features option.
  • 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.
text
https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs

You 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:

bash
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:

.mcp.json
json
{
  "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:

bash
npx plugins add supabase-community/supabase-plugin

Codex

bash
codex mcp add supabase --url "https://mcp.supabase.com/mcp"
codex mcp login supabase

Or add the server to ~/.codex/config.toml yourself, then run the login command:

~/.codex/config.toml
text
[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:

.cursor/mcp.json
json
{
  "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:

bash
agent mcp enable supabase
agent mcp login supabase
agent mcp list

Details on file locations: how to add an MCP server to Cursor.

VS Code

Add this to .vscode/mcp.json in your project:

.vscode/mcp.json
json
{
  "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 supabase inside Gemini CLI. Supabase also has a Gemini CLI extension that bundles the server and skills.
  • Antigravity: add the URL under serverUrl in ~/.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:

json
{
  "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):

text
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=true in the URL. That's expected in read-only mode.
  • Project tools like list_projects are missing: project_ref turns 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.

PluginStack is independent and not affiliated with or endorsed by the companies mentioned. Spotted something out of date? Email pluginstackai@gmail.com.

Get new guides by email

New MCP servers and agent tools, checked by hand. Free, unsubscribe anytime.

The newsletter hasn't started sending yet. Join the list now and we'll email you when the first issue goes out. From PluginStack (pluginstackai@gmail.com). Privacy policy.