Supabase MCP: How to Connect, Configure, and Secure It

Want an AI assistant like Cursor or Claude to talk to your Supabase project? The Supabase MCP server is the official way to do it, built and maintained by Supabase itself. Under the hood it implements Anthropic's Model Context Protocol (MCP), an open standard for how large language models talk to external platforms. Hook it up and an agent can design tables, run SQL, fetch project config, deploy edge functions, read logs, and generate TypeScript types. All from natural language, all without leaving your editor. This guide walks through what the server is, how to set it up, the tools it exposes, and (the part that actually matters) how to scope it so an agent never touches data it shouldn't.

It's a genuinely useful integration. It's also the textbook case for why agent-to-database access needs guardrails. We'll cover both halves honestly.

What is the Supabase MCP server?

It's a first-party server, maintained by Supabase. The GitHub repo supabase/mcp puts it plainly: "Connect Supabase to your AI assistants." The official docs frame it like so: "The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Supabase."

Supabase announced it on April 4, 2025 during a launch week. The early version wired up tools like Cursor and Claude so they could "perform tasks like launching databases, managing tables, fetching config, and querying data on your behalf." Then a remote, OAuth2-authenticated version shipped on October 3, 2025, which broadened client support and meant you no longer had to juggle personal access tokens by hand.

Is it official, and is it free?

Yes on both. The server ships as the npm package @supabase/mcp-server-supabase, with source in the supabase/mcp monorepo. There's also a companion package, @supabase/mcp-server-postgrest, which provides a PostgREST/REST-API-based server for application end users. No separate MCP fee beyond your normal Supabase usage. The one exception is the experimental branching tools, which need a paid plan.

What it lets an AI agent do

You skip the bespoke, per-tool integrations. MCP hands an agent one standardized protocol to operate your backend. Scaffold a whole feature (database table, frontend, backend logic) from a single prompt. Or query Postgres in plain English while you stay put in your IDE.

What can it do: the tool groups

The server exposes 20+ tools, organized into feature groups. Every group is on by default except Storage. Here's the documented set:

• Account: list_projects, get_project, create_project, pause_project, restore_project, list_organizations, get_organization, get_cost, confirm_cost
• Database: list_tables, list_extensions, list_migrations, apply_migration, execute_sql
• Debugging: get_logs, get_advisors
• Development: get_project_url, get_publishable_keys, generate_typescript_types
• Edge Functions: list_edge_functions, get_edge_function, deploy_edge_function
• Docs / Knowledge Base: search_docs
• Branching (experimental, paid plan): create_branch, list_branches, delete_branch, merge_branch, reset_branch, rebase_branch
• Storage (disabled by default): list_storage_buckets, get_storage_config, update_storage_config

One behavior worth knowing. Scope the server to a single project (more on that below) and the account-level tools vanish. The server only sees that one project.

How to set up the Supabase MCP server

A few ways to connect, depending on whether you want the hosted remote server, a local development server, or a self-hosted instance. For most people, the remote server is the recommended path now.

Remote / hosted server (recommended)

The hosted server sits at a fixed URL, https://mcp.supabase.com/mcp, and uses browser-based OAuth (dynamic client registration). No personal access token needed. The client redirects you to log in to Supabase during setup, and you pick the organization that holds your project.

Minimal client config:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

Three URL query parameters tune the behavior:

• read_only=true: runs all queries as a read-only Postgres user and disables mutating tools
• project_ref=<id>: scopes the server to a single project, disabling account-management tools
• features=<comma-separated groups>: chooses which tool groups are exposed

A hardened, project-scoped, read-only URL looks like this:

https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true

Running CI or some other non-interactive environment? Skip the browser flow. Pass a personal access token (created in the Supabase dashboard) via an Authorization header:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

Local stdio server via npx

The original transport runs the npm package over stdio. Still handy for stdio-only clients. The announcement post showed this config:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "<personal-access-token>"
      ]
    }
  }
}

The stdio package takes CLI flags that mirror the hosted query params: --read-only, --project-ref=<id>, --features=<groups>, and --access-token=<pat>. A safer invocation passes the token via environment and scopes access via flags:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

A heads-up for Windows. Many clients can't spawn npx directly, so the common fix is to wrap the command with cmd /c (set "command": "cmd" and prefix the args with "/c", "npx", ...). Check the exact snippet against the current README for your client.

Local Supabase CLI

Running Supabase locally with the CLI? The MCP server shows up at http://localhost:54321/mcp, with a limited tool set.

Self-hosted Supabase

Self-hosted Supabase exposes a /mcp endpoint through the API gateway. One critical caveat: it does not offer OAuth 2.1 and is not intended to be exposed to the internet. You whitelist the Docker bridge gateway IP, then reach it over a VPN or SSH tunnel. The self-hosting guide covers getting the gateway IP via docker inspect, editing the Kong or Envoy config, and tunneling, like so:

ssh -L localhost:8080:localhost:8000 you@your-host

Then point your client at http://localhost:8080/mcp.

Connecting your client

The server works with Cursor, Claude (Desktop and Code), Windsurf, VS Code, ChatGPT, and most MCP-compatible assistants. In Cursor, add the server under Settings > Cursor Settings > Tools & MCP. In Claude Code, run /mcp to confirm supabase is active. Some clients want a restart after authorization before they'll detect all the tools.

Configuration and scoping

Those three levers above (read_only, project_ref, and features) aren't just convenience options. They're your primary safety controls.

• Read-only mode runs SQL as a read-only Postgres user and disables mutating tools like apply_migration, create_project, deploy_edge_function, and branch/storage mutations. Writes get blocked no matter what a prompt tries.
• Project scoping limits the server to one project and strips out account-level tools such as list_projects and list_organizations.
• Feature selection lets you expose only the tool groups an agent actually needs.

Is Supabase MCP safe? The 2025 SQL-leak lesson

Wiring any database to an LLM carries real risk, and Supabase MCP became the canonical case study. In 2025, General Analysis showed that the server could leak an entire SQL database. Simon Willison wrote it up as an example of what he calls the "lethal trifecta": an agent with (1) access to private data, (2) exposure to untrusted content, and (3) the ability to communicate externally.

Here's the proof of concept. The MCP server runs with service_role credentials, which bypass Row-Level Security. An attacker files a support ticket containing hidden instructions, say, telling the assistant to read the integration_tokens table and paste its contents into the ticket thread. A developer later reviews tickets through Cursor. The assistant treats the ticket text as instructions, runs the SELECT, and writes the private data back into the visible thread. That's indirect prompt injection, which Supabase names as the top concern unique to connecting LLMs to your database.

Supabase responded with a Defense in Depth post (September 16, 2025) that added read-only mode, project scoping, feature groups, and query-result wrapping that warns the model not to follow embedded commands. They were candid about the limits, noting these measures "reduced risk but did not eliminate it" and that "guardrails alone aren't enough."

How to lock it down

Supabase and the researchers agree on the playbook:

• Never connect AI agents directly to production data. Use a development, staging, or anonymized dataset.
• Enable read-only mode any time you're touching real data.
• Scope to a single project and limit feature groups to what's needed.
• Use database branching for safe testing.
• Keep manual tool-call approval on in your client.
• Don't expose the server to your end users.

Troubleshooting common errors

Fixes for the usual suspects are scattered across GitHub and forums. Here they are in one place:

• `Cannot find module` with npx: clear the npm cache with npm cache clean --force, or drop @latest and pin a specific version.
• A server named `supabase` forcing SSE/OAuth and ignoring stdio config: a known workaround is renaming the server entry to something like supabase-local. (Issue.)
• Auth not triggering / "Server Disconnected" in Claude Code or Cursor: restart the client after authorizing so it re-detects tools, and confirm your project-ref resolves. (Discussion.)

How AI agents actually use MCP servers as tools

The Supabase MCP server is one concrete instance of a much broader pattern: AI agents that use MCP servers as tools to act on external systems through APIs. A database is just one such system. The same architecture covers payment platforms, ticketing systems, internal services, and more. The agent doesn't hard-code an integration. It discovers tools, reasons about which to call, and acts.

That's exactly the model gamut.so (by Datawizz) is built around: an AI agent knowledge workforce where agents use MCP servers as tools, triggered by events and acting through APIs on real systems. The security lessons above aren't a footnote in that world. They're the design center. A dev-convenience tool pointed at a development project is one thing. An agent workforce acting against production systems demands scoping, read-only paths, project isolation, and event-gated triggers as first-class concerns.

FAQ

What is the Supabase MCP server?

An official, Supabase-maintained server implementing the Model Context Protocol that connects AI assistants to a Supabase project so they can run SQL, manage tables, deploy edge functions, and more.

Is it the official Supabase MCP server?

Yes. It's supabase/mcp on GitHub and @supabase/mcp-server-supabase on npm, maintained by Supabase.

How do I connect Supabase MCP to Cursor or Claude?

Use the remote server at https://mcp.supabase.com/mcp (OAuth, no token needed) or run npx @supabase/mcp-server-supabase. In Cursor, add it under Settings > Tools & MCP; in Claude Code, run /mcp to confirm it's active.

How do I make the Supabase MCP server read-only?

Add read_only=true to the hosted URL, or pass --read-only to the npx command. It runs queries as a read-only Postgres user and disables mutating tools.

Local vs remote: which should I use?

Use the remote hosted server for most workflows (no Node setup, OAuth). Use the local CLI server at http://localhost:54321/mcp for local development, and npx for stdio-only clients.

Is it safe to connect Supabase MCP to production?

No. Supabase explicitly recommends never connecting AI agents directly to production data. Use a development or anonymized dataset, read-only mode, and project scoping.

Does the Supabase MCP server require a paid plan?

No, except for the experimental branching tools, which require a paid plan.