What the Supabase MCP Server Actually Gives Claude Code
Connect Claude Code to Supabase by adding Supabase's own hosted MCP server, at https://mcp.supabase.com/mcp, and authenticating once through your browser. Once it is connected, Claude Code can list your tables, write and apply database migrations, run SQL queries, read project logs to debug an issue, and generate TypeScript types straight from your schema, all inside the same session where you are already building.
This is a server Supabase built and runs themselves, not a community package stitched together against their API. That is why it keeps working when Supabase ships a change instead of quietly going stale. The tools are grouped into feature sets - database, debugging, development, functions, branching, docs, account, and storage - and you choose which groups to turn on when you register the server.
How to Connect It: the Hosted Route
The hosted route is the one Supabase documents as the default, and it is the one I would use. It authenticates through your browser, so there is no token to generate, paste, or accidentally commit.
- In your project folder, run claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp" to register the server. Using --scope project writes it to a .mcp.json in the repo so the connection travels with the project.
- In a regular terminal (not an IDE extension), run claude /mcp, select the supabase server, and choose Authenticate. A browser window opens where you sign in to Supabase and grant access.
- Pick the organization that contains the project you want to work with when you sign in. After that, ask Claude Code something like: what tables are in the database, use the MCP tools. If it answers with your real schema, the connection is live.
If you would rather not put the URL in a shared repo file, drop the --scope project flag and it registers only for you on that machine. Either way, the authentication is per-account through the browser, not a secret baked into the config.
The Three Settings That Keep It Safe
Do not point a wide-open MCP connection at a production database. The server acts with your developer permissions, so an LLM that gets confused - or gets fed a malicious instruction hidden inside your own data - can run real queries. Three URL parameters shrink that risk to almost nothing, and you set them by editing the server URL you registered.
The three guardrails, and what each one does
| Parameter | What it does | Example |
|---|---|---|
| project_ref=<id> | Scopes the server to one project and disables the account-level tools that can create, pause, or list other projects | ?project_ref=abc123 |
| read_only=true | Runs every query as a read-only Postgres user, so the model can look but cannot write, drop, or alter | ?read_only=true |
| features=<groups> | Turns on only the tool groups you name, so the model cannot reach for abilities you never intended to expose | ?features=database,docs |
You combine them with & in the URL, like https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true. For a database you cannot afford to break, scope it, set it read-only, and restrict the features to the smallest set that answers your question. Widen access only when a specific task genuinely needs to write.
What Actually Broke the First Time I Wired It Up
The first time I set this up I used the old npx-spawned local server, and Claude Code reported it as connected. It was not really connected. The server showed as present, but none of its tools were discoverable, so the model just quietly failed to use them with no error to explain why. I spent longer than I would like re-checking my token before realizing the setup itself was the problem, not the credential.
Switching to the hosted remote server and authenticating through the browser fixed it in one pass. The lesson I would save you: if Claude Code says a Supabase MCP server is connected but never actually uses any Supabase tools, do not assume your token is wrong. Confirm the tools are discoverable first by running /mcp and checking the tool list, and prefer the hosted route so there is no token in the loop to doubt at all.
What This Is Actually Good For
The everyday win is that Claude Code stops guessing at your schema. Instead of you pasting a table definition into a prompt, it reads the real one and writes SQL or a migration against what is actually there.
- Ask for a migration in plain English and have Claude Code write it, then apply it against a development branch rather than typing DDL by hand.
- Debug a slow or failing feature by having it pull the project logs and run a read-only query to see the actual rows, not a mock of them.
- Generate up-to-date TypeScript types from the live schema so your app code and your database stop drifting apart.
- Run a report - the real numbers behind a client dashboard - with a read-only SQL query instead of exporting a CSV and eyeballing it.
Branching deserves its own note. Supabase's branching feature lets Claude Code create a throwaway development database, make changes there, and merge back when they are proven, so you are never testing a risky migration against live data. It is on a paid plan and worth it the moment real user data is involved.
When Not to Bother With It
Skip it for a one-off script with no database behind it, or a throwaway prototype where you do not care about the schema surviving. The setup earns its keep once there is a living project - real tables, real migrations, a schema you would otherwise be re-describing to the model every session.
Short, practical drops on skills, MCP, agents, prompts, and more. No spam, unsubscribe anytime.
Frequently asked questions
How do I connect Claude Code to Supabase?
Register Supabase's hosted MCP server with claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp", then run claude /mcp, select the supabase server, and choose Authenticate. A browser window opens where you sign in to Supabase and grant access. No personal access token is required for the hosted route.
Do I need a Supabase access token to connect Claude Code?
Not for the hosted server. It authenticates through your browser using dynamic client registration, so there is no token to create or store. You only need a personal access token for a CI environment where a browser login is not possible, where you pass it as an Authorization header instead.
How do I stop Claude Code from writing to my production Supabase database?
Add read_only=true to the server URL so every query runs as a read-only Postgres user, and add project_ref=<id> to scope the server to one project and disable account-level tools. Combine them like https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true, and keep manual approval of tool calls on so you can review each query first.
What can Claude Code do once it is connected to Supabase?
It can list tables and extensions, write and apply migrations, run SQL queries, pull project logs to debug, generate TypeScript types from your schema, and manage development branches on a paid plan. The exact abilities depend on which feature groups you enabled in the server URL.
Why does the Supabase MCP server show as connected but no tools work?
This is the classic symptom of the older local npx setup, where the server registers but its tools are not discovered, with no error shown. Switch to the hosted remote server at https://mcp.supabase.com/mcp and authenticate through the browser, then run /mcp to confirm the tools are actually listed.
Last reviewed by David Iya on September 6, 2026
