How to Connect Claude Code to Supabase with MCP

Connecting Claude Code to Supabase lets Claude list your tables, run SQL, apply migrations, read logs and generate TypeScript types while it writes your app code. Supabase hosts the server and documents Claude Code by name. The default tool set can change your database, so the setup choices below matter.

Checked against: Supabase's MCP guide and Claude Code's MCP documentation on 28 October 2026. eSEOspace did not run these steps; menus can change, so follow the vendor's page if it differs.

Before you start

You need Claude Code installed and a Supabase account. Know which organization holds the project you want. Supabase says to choose that organization during sign-in.

Decide your scope before you connect. Supabase's recommendations say to connect to production "only when the task requires production evidence." For anything else, use a development project or a branch. Branching tools need a paid plan.

If you develop locally with the Supabase CLI, the server is at http://localhost:54321/mcp instead. Supabase notes the CLI and self-hosted versions offer fewer tools and no OAuth 2.1.

Steps

1. From your project folder, run Supabase's command:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

Or add this to .mcp.json yourself:

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

1. Authenticate. Supabase says to run this in a regular terminal, not the IDE extension:

claude /mcp

1. Select the "supabase" server, then "Authenticate". Sign in to Supabase in the browser window and grant access.
2. Pick the organization that contains your project.

Because this is a project-scoped server, Claude Code's docs say it asks for your approval before using servers from .mcp.json. Teammates who clone the repo get the same prompt.

Use a safer URL

Supabase's URL parameters can be combined. This example scopes to one project and makes every query read-only:

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

Add &features=database,docs to load only those tool groups. Replace abc123 with your project ref. You can also build the URL in the configuration panel on Supabase's MCP page.

CI and headless runs

For CI, where browser OAuth isn't possible, Supabase says to create a personal access token and pass it as a header. Its Claude Code example:

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

Scope that token to the one project and only the permissions your enabled tools need.

Check that it works

Run claude mcp list and look for ✔ Connected. A ⏸ Pending approval status means you still need to start claude interactively and approve the .mcp.json server.

Example prompts:

• "What tables are there in the database? Use MCP tools." (Supabase's own test prompt; uses list_tables)
• "List the migrations applied to this project." (uses list_migrations)
• "Run the security and performance advisors and summarize what they flag." (uses get_advisors)

All three only read. Supabase suggests its AI Prompts collection for more.

Permissions and safety

Supabase lists these controls in its docs:

Supabase also uses elicitation, an MCP feature where a server pauses a tool call to ask you something. It asks before creating paid projects or branches, and before destructive SQL when your client supports forms. Supabase calls these prompts "a guardrail, not a guarantee of human review." Don't add skip_elicitations unless you know why.

In Claude Code, keep mcp__supabase__execute_sql and mcp__supabase__apply_migration on ask. Claude Code's permission rules let you allow read tools by name while writes still prompt.

Enter Edge Function secret values in the Supabase Dashboard, never in chat. Read prompt injection through MCP tool results, excessive permissions and the MCP Security Center.

If it doesn't work

• Wrong organization. You signed in to the org without your project. Clear authentication in /mcp and sign in again.
• Tools missing after sign-in. Supabase says some clients need a restart to detect all tools.
• Server pending approval. Start claude in the project folder and approve the .mcp.json server. Claude Code ignores approvals committed to the repo until you trust the folder.
• No cost or SQL confirmation dialog. Supabase has troubleshooting articles for both. Your client may not support form elicitation.
• CI fails to connect. Check that SUPABASE_ACCESS_TOKEN and SUPABASE_PROJECT_REF are set. Claude Code reports a failed connection, not an OAuth prompt, when a configured header is rejected.

Next step

Read the Supabase MCP server profile for every tool group. Browse other setups in the connection guides hub, including Cursor with Supabase. If you'd like help wiring a safe database workflow, see our Claude Code consulting service.

Frequently asked questions