What Does the Supabase MCP Server Do and How Do You Set It Up?

The Supabase MCP server connects AI assistants to the entire Supabase platform through the Model Context Protocol (MCP), the open standard Anthropic created in November 2024. The server exposes 32 tools across 8 feature groups: the Postgres database, auth, storage, edge functions, branching, debugging, project management, and documentation search. Claude Code, Cursor, and VS Code connect to it through one hosted endpoint and run SQL, apply migrations, and deploy functions in natural language.

Supabase builds and maintains the server, which makes it a managed gateway in the database category’s taxonomy: it routes through the Supabase platform API and inherits the platform’s authentication, instead of holding a raw connection string the way a connection wrapper does. Supabase launched the server on April 4, 2025, moved it to a hosted remote endpoint on October 3, 2025, and shipped it as an official Claude connector on February 3, 2026 (Supabase blog).

This page covers the 32 tools and how feature groups trim them, the OAuth and access-token auth paths, the exact configuration per client, the failures you hit and their fixes, and the July 2025 prompt-injection incident with the three URL parameters that contain it.

All database MCP servers · What MCP is and how it works

What Does the Supabase MCP Server Expose?

The Supabase MCP server exposes 32 tools across 8 feature groups: account, docs, database, debugging, development, functions, storage, and branching. The model lists tables, runs SQL, applies migrations, deploys edge functions, and reads logs through tool calls.

The feature groups map to the platform’s surface area, and each group loads a named set of tools:

Four workflows show what the tool set produces in practice:

• Schema design with policies. “Create a user_profiles table with row-level security policies” chains list_tables, apply_migration, and execute_sql: the model reads the existing schema, writes the migration, and applies it as a versioned change.
• Type generation. “Generate TypeScript types for my database” runs generate_typescript_types against the live schema, so the types match the database, not a guess.
• Log-driven debugging. “Pull the latest edge function logs and diagnose why my webhook is failing” chains get_logs with search_docs: the model reads the real error and checks it against current documentation.
• Safe provisioning. Any prompt that creates a project or branch routes through confirm_cost first, which forces an explicit confirmation before anything bills.

Two defaults shape what the model sees. First, 7 of the 8 groups load when no features parameter is set: storage stays off until you enable it. Second, the account group disappears entirely when the server is scoped to one project. That second default is a tradeoff the setup section returns to: scoping is the right security call, and it costs you the project-provisioning tools.

Every group you load adds tool definitions to the model’s context window before any call happens. Independent measurement puts MCP tool definitions at 250 tokens each on average (MCP Token Counter, MCP Playground, April 2026), which places the full Supabase tool set near 8,000 tokens of fixed overhead per request. The features parameter is the control: features=database,docs loads 6 tool definitions instead of 30 or more, and the overhead drops below 1,500 tokens.

One version caveat applies. The server is pre-1.0, and the README states that breaking changes between versions are expected (supabase/mcp, GitHub). Tool names and groupings can shift; the configuration patterns below are current as of June 2026.

How Does the Supabase MCP Server Authenticate?

The server authenticates through an OAuth 2.1 browser flow for interactive clients and a personal access token passed as an Authorization header for CI and headless environments. Self-hosted instances get no OAuth at all.

Three environments, three auth paths:

• Interactive clients (Claude Code, Cursor, VS Code). The hosted server uses dynamic client registration: the first connection opens a browser window, you log in to Supabase and grant organization access, and the client receives a scoped, expiring token. No key sits in the config file, and no personal access token is required for interactive use (Supabase docs).
• CI and headless environments. Generate a personal access token at Supabase account settings, then pass it as a header: Authorization: Bearer $SUPABASE_ACCESS_TOKEN. Inject the token through an environment variable, never hardcoded in the config (Supabase docs).
• Self-hosted Supabase. The self-hosted MCP server runs behind your own gateway (Kong in the default stack) with a limited tool subset and no OAuth 2.1 support. Authentication is whatever your internal API enforces.

The OAuth path is the reason the remote server replaced the original npm package as the default: the April 2025 server required pasting a personal access token into the config file in plain text, and the October 2025 remote endpoint removed that requirement for interactive use.

How Do You Set Up the Supabase MCP Server?

Set up the Supabase MCP server by adding one hosted URL to your client’s config: https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true. The URL carries the three parameters that control everything: project_ref scopes access to one project, read_only executes all queries as a read-only Postgres user, and features selects tool groups.

Omit project_ref and the server reaches every project in your Supabase account. Set it. The Supabase dashboard’s MCP connection tab generates the full URL with the parameters populated, and the per-client blocks below show where that URL goes.

Claude Code

Add the server with one command:

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

The first tool call triggers the OAuth browser flow. For CI runs, pass the token header instead: --header "Authorization: Bearer $SUPABASE_ACCESS_TOKEN". The full client walkthrough, including verification and scope management, is at set up MCP in Claude Code.

Cursor

Add an entry to .cursor/mcp.json at the project root:

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

Cursor prompts for the OAuth grant when the server first connects, and the config travels with the repository. Client-side steps are at add MCP servers to Cursor.

VS Code

VS Code reaches MCP through GitHub Copilot Chat, and its JSON root key is "servers", not "mcpServers". Copying a Cursor config without changing that key is the first error developers hit. The same hosted URL goes in the url field with "type": "http".

Codex CLI, Windsurf, and other clients

Codex CLI configures servers in ~/.codex/config.toml; clients without native HTTP-plus-OAuth support bridge through the mcp-remote package, run as npx -y mcp-remote https://mcp.supabase.com/mcp?project_ref=<your-project-ref>. Windsurf takes the hosted URL in its mcp_config.json. Antigravity, OpenCode, Warp, and JetBrains Junie follow the same pattern: paste the hosted URL where the client accepts a remote MCP server, and approve the OAuth grant. Each client’s exact file path is in its setup guide.

Local development

The Supabase CLI exposes a local MCP endpoint at http://localhost:54321/mcp when a local stack runs. The local server carries a limited tool subset and omits OAuth: it serves local schema and query work, not project management.

Remote, local, or self-hosted: which deployment fits?

Three deployments of the same server exist, and the environment picks for you:

The remote endpoint is the default and the maintained center of gravity. The local and self-hosted servers trade tool coverage for environment fit, and both drop the OAuth flow.

Verify the connection

A working connection shows the Supabase tool list in the client’s MCP panel: in Cursor, under Settings, Cursor Settings, Tools & MCP; in Claude Code, through claude mcp list. A test prompt (“list my tables”) returns real table names. A connection that shows the server but zero tools is the second diagnostic case below.

Why Isn’t the Supabase MCP Server Working?

The six most common failures are an unapproved OAuth grant, the wrong token type, a Claude Code server-name collision, a stale npm config, a client that cannot complete dynamic client registration, and a self-hosted instance with no OAuth at all.

• Unauthorized. Please provide a valid access token to the MCP server via the --access-token flag or SUPABASE_ACCESS_TOKEN. This is the legacy npm server’s auth failure, reported in both Claude Code and Cursor. The recurring cause is the wrong token type: the anon key from project settings fails here, because the server requires a personal access token from account settings (supabase/supabase #37569, #38926). The hosted endpoint with the OAuth flow removes the token from the config entirely.
• Cursor shows “No tools or prompts” with a red error indicator. The documented cause is the npm package pinned as @supabase/mcp-server-supabase@latest, which breaks dependency resolution and throws Error: Cannot find module './type/validate.js' (supabase/supabase #38143). Drop @latest from the package name, or replace the npm config with the hosted URL.
• Claude Code ignores a local stdio config when the server is named supabase. Claude Code applies hardcoded OAuth handling to that exact server name and overrides an explicit "type": "stdio" entry. Renaming the server, supabase-local in the reported case, restores the stdio config (anthropics/claude-code #21368, January 2026).
• OpenCode returns 401 Unauthorized then Dynamic client registration failed: HTTP 404. OpenCode cannot complete the hosted server’s registration flow as of January 2026 (anomalyco/opencode #6842). The bridge path through mcp-remote with a personal access token header is the workaround.
• VS Code hangs at “Awaiting verification” against self-hosted Supabase. Self-hosted instances ship no OAuth 2.1, so the browser flow opens and never completes (supabase discussion #39996). Pass a token through the Authorization header and protect the endpoint at the network level.
• get_project and other account tools are missing. This is scoping working as designed, not a failure. The account group unloads when project_ref is set. Run project-provisioning tasks through an unscoped session, then return to the scoped URL for daily work.

Three generations of this server exist: the npm package (April 2025), the hosted remote endpoint (October 2025), and the official Claude connector (February 3, 2026). The first two error cases above are npm-generation failures that tutorials written before October 2025 still reproduce. Replace npx @supabase/mcp-server-supabase configs with the hosted URL; the remote endpoint is the maintained path, and the maintenance-recency rule that governs every server in the directory applies to versions of the same server too.

A connected, verified server can now read and write a live Supabase project. What it is allowed to do there is the supplementary half of this page.

Is the Supabase MCP Server Safe?

The Supabase MCP server is safe when you scope it to a development project, set read-only mode, and trim feature groups. Unscoped, write-enabled, production-connected setups are the configuration a documented attack exploited.

The incident is the most cited MCP security case study. In July 2025, researchers at General Analysis published “Supabase MCP can leak your entire SQL database”: a support-ticket field in a demo SaaS carried hidden instructions, a developer reviewed tickets through Cursor with the Supabase server connected, and the model followed the embedded instructions, queried private data at the server’s service_role privilege, and wrote the results back into the attacker-visible ticket (General Analysis, July 2025). Simon Willison classified it as a lethal trifecta attack: private data access, exposure to untrusted instructions, and a write path back to the attacker, combined in one server (Simon Willison, July 6, 2025).

Supabase’s response, “Defense in Depth for MCP Servers” (September 2025), states that no customer incident occurred, that row-level security stayed enforced, and that the demo’s exposure came from the server operating at a privilege above RLS. The response also names the residual risk plainly: client-side tool-call approval mitigates injection, and approval fatigue erodes it.

The containment maps to the three URL parameters this page configured, and each parameter closes one link in the demonstrated attack chain:

1. read_only=true executes every query as a read-only Postgres user. The attack needed a write to put stolen data where the attacker can see it; the write-back path closes at the role level, below the model, where an injected prompt cannot reach.
2. project_ref=<ref> limits the blast radius to one project. An injected instruction cannot reach your other projects’ data, and the account tools that provision and list projects unload entirely.
3. features=database,docs removes the tool groups a workflow does not need. Fewer tools, fewer actions an injected instruction can invoke, and a smaller tool surface for the model to misread.

Three platform-level rules complete the model: connect the server to a development project, never production; keep it out of customer-facing surfaces, because it operates at developer permissions; and treat RLS policies as the last line of defense, not the first. The cross-server threat model, including tool poisoning and the vetting checklist, is at MCP security.

Should You Use the Supabase MCP Server or the Postgres MCP Server?

Use the Supabase server when your project runs on Supabase, and the Postgres server when you run PostgreSQL anywhere else. The Supabase server is a managed gateway: it exposes the platform (database plus auth, storage, functions, branching) through OAuth and the platform API. The Postgres server is a connection wrapper: it holds a connection string to any PostgreSQL instance and exposes the engine alone, with EXPLAIN plans and deeper query analysis.

A Supabase team gains nothing from the wrapper except lost platform tools; a self-hosted Postgres team cannot use the gateway at all.

How Much Does the Supabase MCP Server Cost?

The server is free. The costs are platform costs: a Supabase project on the free tier runs the server at no charge, and paid tiers price by database size, bandwidth, and compute. The free tier covers two projects, which fits the server’s intended use, a development project the model can touch. Teams running the branching tools need a paid plan, because database branches bill as compute. Plan details are on Supabase’s pricing page, and the confirm_cost tool forces an explicit confirmation before the model provisions anything that bills.

Supabase MCP Server Questions

What Is Supabase MCP?

Supabase MCP is the official server that connects AI assistants to the Supabase platform through the Model Context Protocol. It exposes 32 tools across 8 feature groups covering the database, auth, storage, edge functions, and branching. Supabase maintains it, hosts it at mcp.supabase.com, and authenticates it through OAuth 2.1 or a personal access token.

Can the Supabase MCP Server Run SQL Queries?

Yes. The database feature group exposes SQL execution, table listing, and schema reads, and the model writes and runs the queries from natural-language prompts. The read_only=true parameter restricts execution to a read-only Postgres user, which blocks INSERT, UPDATE, DELETE, and DDL statements at the role level. Leave the parameter off only when a workflow needs writes, and point that workflow at a development branch.

How Do You Get a Supabase Access Token for MCP?

Generate a personal access token at Supabase account settings under Access Tokens, name it for its purpose, and pass it as Authorization: Bearer $SUPABASE_ACCESS_TOKEN in the server config. Interactive clients skip this entirely: the OAuth browser flow issues a scoped token on first connection. The manual token path serves CI pipelines and clients without OAuth support.

How Do You Change Read-Only to Full Access?

Remove read_only=true from the server URL and reconnect the client. The change takes effect on the next connection, and it widens what an injected instruction can do, the exact write path the July 2025 demonstration used. Switch a write-enabled server to a development branch, keep project_ref set, and trim features to the groups the write workflow needs.

Every path on this page runs through one endpoint: a hosted URL, three parameters, and a tool set the model discovers on connection. Configure the parameters before the first query, and the server that can manage your whole platform stays scoped to exactly the slice you handed it.