How to Install and Use the Supabase MCP with Claude Code (2026)

The first time I connected Claude Code to a Supabase project, I asked it "which users signed up but never created a project?" and it wrote the join, ran it, and handed me 43 rows. No copy-pasting SQL into the dashboard, no describing my schema in a paragraph. The agent read the tables itself and answered.

That's what the Supabase MCP server does: it turns your database from something you tell the agent about into something the agent can see. Here's how to install it, wire it up safely, and use it without handing a robot the keys to your production data.

What you're actually setting up

MCP, the Model Context Protocol, is the standard that lets agents talk to external tools and data. The Supabase MCP is one server speaking that protocol, and Claude Code is the client that uses it.

Step 1: Generate a Supabase access token

In your Supabase dashboard, go to account settings and find access tokens. Create a new one and name it something you'll recognize later, like "claude-code-dev." Copy it now, because Supabase shows it once.

Keep this token out of any file you might commit to git. You'll put it in an environment variable or your MCP config's secret field, never inline in source you push.

Step 2: Add the server to Claude Code's MCP config

Claude Code reads MCP servers from its config. Add the Supabase entry, passing your project reference and the access token through the environment:

\\\json { "mcpServers": { "supabase": { "command": "npx", "args": [ "-y", "@supabase/mcp-server-supabase@latest", "--read-only", "--project-ref=YOUR_PROJECT_REF" ], "env": { "SUPABASE_ACCESS_TOKEN": "your-token-here" } } } } \\\

Two flags here matter more than the rest. \--read-only\ means the agent can look but not change, which is exactly where you want to start. \--project-ref\ pins the server to one project so the agent can't wander into your other databases.

Restart Claude Code after editing the config so it picks up the new server.

Step 3: Confirm the connection

Ask the agent something it can only answer by reading the live database, like "list my tables and their row counts." If the MCP is connected, you'll get a real answer pulled from your schema. If you get a shrug, check three things: the token is valid, the project ref is correct, and Claude Code was restarted.

This confirmation step is worth the thirty seconds. A silently broken MCP looks identical to a working one until the agent quietly hallucinates a schema instead of reading yours.

Step 4: Use it for the boring, valuable work

Read-only is where the Supabase MCP earns its place. Some things I run constantly:

• "Show me the schema for the orders table and its foreign keys."
• "How many sign-ups per day for the last two weeks?"
• "Find rows in payments where status is pending and created more than 24 hours ago."
• "Explain why this query is slow and suggest an index."

The agent writes the SQL, runs it against your real data, and explains the result. For exploring an unfamiliar database or answering a one-off business question, it's faster than opening the SQL editor and remembering your own column names.

Step 5: Turning on writes, carefully

At some point you'll want the agent to create a table or apply a migration. That means dropping \--read-only\, and that's a decision, not a default.

Before you do:

1. Do it on a development or staging project, never production first. 2. Read every migration the agent proposes before it runs. Migrations are easy to write and hard to undo. 3. Keep a backup or a point-in-time recovery you trust. 4. Add a human approval step in your own head: nothing destructive runs without you reading it.

A good pattern is to let the agent draft the migration as a file, review it yourself, and apply it deliberately, rather than letting it apply changes directly. The convenience of "just do it" is not worth waking up to a dropped column.

The safety rules, in one place

The Supabase MCP is genuinely useful and genuinely capable of damage, so the guardrails aren't optional:

• Start read-only. Add writes only when you have a reason and a backup.
• One project per token, scoped with \--project-ref\.
• Token in an environment variable or secret, never in committed code.
• Development and staging before production, always.
• Read every write the agent proposes. You are the approval step.

None of this is hard. It's the same caution you'd give a new engineer with database access, just applied to an agent that moves faster.

Where it fits with other MCPs and skills

The Supabase MCP rarely works alone. Paired with the [GitHub MCP](/blog/how-to-install-github-mcp-claude-code-connect-repos-2026), the agent can read your schema and your code together, which is where it gets genuinely useful for debugging. And if you want to understand the protocol well enough to build your own server, [how to build an MCP server](/blog/how-to-build-an-mcp-server-claude-skills) walks through it.

The MCP gives the agent reach. A skill gives it judgment about how to use that reach. For database work, that combination, live connection plus good practices, is what separates a helpful agent from a dangerous one.

When it breaks: quick troubleshooting

Most Supabase MCP problems fall into a handful of buckets, and they're quick to fix once you know the pattern.

The agent says it can't find the server. The config didn't load, almost always because Claude Code wasn't restarted after you edited it. Restart, then ask it to list your MCP servers to confirm.

You get an authentication error. The token is wrong, expired, or scoped to the wrong account. Generate a fresh one in Supabase account settings, paste it into the env block, and restart. If it still fails, check you copied the whole token with no trailing space.

The agent connects but returns nothing or hallucinates a schema. Usually the project ref is wrong, so it's authenticated to your account but pointed at no project, or the wrong one. Double-check the --project-ref value against the one in your Supabase project settings.

Writes fail even though you want them. You left --read-only in the args, which is doing exactly its job. Remove it deliberately, and only after you've read the safety section above twice.

The server is slow on a big database. The agent may be pulling more than it needs. Ask for specific columns and a LIMIT rather than "show me everything," and it stays fast and cheap.

When something genuinely won't resolve, the official Supabase MCP repository on GitHub is the source of truth for the current flags and known issues. The protocol moves quickly, and a flag that worked last quarter occasionally changes, so check the repo's README before assuming your setup is broken.

FAQ

What does the Supabase MCP let Claude Code do? Query tables, inspect schema, run SQL, manage migrations, and read logs against your live project, without copy-pasting between the dashboard and the chat.

Is it safe to connect to production? Not by default. Start with dev or staging, use read-only for analysis, keep the token in an environment variable, and gate every write behind your own review.

Where do I get the access token? In your Supabase account settings under access tokens. Treat it like a password: environment variable only, never in source control, and rotate it if it leaks.

MCP server vs Supabase skill? The MCP is the live connection that lets the agent run queries. A skill is the know-how that helps it run them well. Serious setups use both.