Here is a failure mode every developer who builds with AI coding agents eventually hits. You ask Claude Code to write a query, it produces clean-looking SQL, and then at runtime you get a table-not-found error. Or a column name is slightly off. Or the agent generates a migration that contradicts the one committed last week. The code looks right. It is confidently wrong.
The root cause is not Claude being bad at SQL — it is that Claude was writing against a mental model of your schema, not the real one. The Supabase MCP server closes that gap. Once connected, Claude Code can introspect your actual tables, columns, foreign keys, RLS policies, and migration history on demand, in real time, without you copy-pasting a single line. This guide walks through setup, verification, and how to get the most out of it — including how AppHandoff layers on top to tie database context to API contracts and handoff tickets.
If you are new to MCP, the short version is that it is an open protocol that lets an AI agent call tools on an external server. Your editor (Claude Code, Cursor, Codex) acts as the MCP client; the external system runs an MCP server. For a longer explanation, see our developer guide to MCP. For a broader look at the best servers to add to your setup, see the hub post.
What Supabase MCP Provides
The official @supabase/mcp-server-supabase package exposes a comprehensive set of tools. Schema introspection is the headline feature: the agent can list every table in your database, describe its columns and types, inspect foreign key relationships, and read row-level security policy definitions. This gives Claude Code a first-class mental model of your actual database rather than one reconstructed from old migration files or partial context in the system prompt.
Beyond schema, the server supports live table queries so the agent can read sample data, check row counts, or inspect specific records to verify its assumptions. Migration history is exposed so Claude can see what has already been applied, preventing it from generating duplicate or conflicting changes. Edge function management tools let the agent list deployed functions and check their metadata. Project management tools cover storage buckets, project settings, and environment variable access (read-only). The full tool surface is broader than most developers expect — Supabase has built MCP as a proper first-class integration, not an afterthought.
For comparison: a raw PostgreSQL connection (a connection string in a .env file) gives the agent SQL execution capability but nothing else. No migration history, no project metadata, no edge function visibility, and no guardrails. The Supabase MCP server wraps that SQL access in a structured, auditable, capability-scoped layer. Our companion post on PostgreSQL MCP servers covers the tradeoffs in depth.
Step 1: Connect Supabase MCP to Claude Code
You need two things before running the setup command: Node.js (or Bun) on your machine so npx works, and a Supabase personal access token. Get the token from app.supabase.com/account/tokens — click "Generate new token", give it a descriptive name like claude-code-dev, and copy it immediately (you will not see it again). The token scopes access to all projects in your Supabase account, so treat it as a secret.
With the token in hand, run this single command in your terminal:
claude mcp add supabase -- npx -y @supabase/mcp-server-supabase@latest --access-token <YOUR_PERSONAL_ACCESS_TOKEN>Claude Code registers this as a named MCP server called supabase in your user-level config. The npx -y flag auto-installs the package if it is not already cached, so there is no separate install step. The server runs as a local subprocess (stdio transport) — it starts when Claude Code starts and is torn down when it exits.
To make this project-scoped instead of global (useful if different projects use different Supabase accounts), add it to .claude/settings.json in your project root instead:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--access-token",
"${SUPABASE_ACCESS_TOKEN}"
]
}
}
}The ${SUPABASE_ACCESS_TOKEN} syntax reads the value from your shell environment, keeping the token out of the committed config file. Add SUPABASE_ACCESS_TOKEN=... to your local .env or shell profile. If you use Cursor, the equivalent config goes into .cursor/mcp.json with the same structure under an mcpServers key — see the FAQ below for the exact Cursor snippet.
Step 2: Verify the Connection
Restart Claude Code (or open a new terminal session) so it picks up the newly registered server. Then open the agent and ask a plain-language question that requires live database access:
Using the Supabase MCP, list all tables in my database and describe their columns.If the connection is working, Claude will respond with a structured list — table names, column names, data types, nullability constraints, and foreign key relationships drawn from your live schema. It will not guess; it will read. If you see an error like Server not found or Access token invalid, jump to the troubleshooting section below.
A second useful verification is to ask Claude to check the migration history:
Using the Supabase MCP, show me the 10 most recent migrations applied to my database.This confirms that migration history access is working and, practically, gives you a quick sanity check on the state of your database before starting a coding session.
What Your Agent Can Do Now
With the Supabase MCP connected, Claude Code's database-related capabilities shift meaningfully. Here is what changes in practice:
Accurate query generation. Claude writes queries against the actual column names in your schema. No more undefined column errors from misremembered field names or stale context.
Conflict-free migrations. Before generating a new migration, Claude can check what already exists. It will not add a column that is already there or drop a table that is still referenced by a foreign key.
RLS policy awareness. Claude can read your row-level security policies before writing queries that depend on them — catching policy gaps before they become auth bugs.
Type generation verification. If you use Supabase's generated TypeScript types, Claude can compare the live schema against your generated type file and flag drift — the same check a CI types step would catch, but surfaced during development instead.
Edge function coordination. Claude can list deployed edge functions and their names before writing code that calls them, eliminating the category of bugs where the caller and callee disagree on the function URL.
Data-informed decisions. In development environments, Claude can run sample queries to understand the actual shape and volume of data, writing pagination logic that reflects reality rather than assumptions.
Supabase MCP vs. Connecting via Connection String
Developers sometimes ask whether it is simpler to just give Claude a direct PostgreSQL connection string. The MCP approach is safer and richer — here is why.
Safety. A raw connection string gives Claude unrestricted SQL access. An agent operating in agentic mode can execute writes, drops, or truncates — destructive operations that are hard to undo. The Supabase MCP server scopes what the agent can do via the tool interface, and read-only tools are the default. You are not relying on prompt instructions to prevent destructive operations; the tool surface enforces it.
Richness. A connection string gives the agent a way to run SQL. The MCP server gives the agent structured tools: list_tables, describe_table, get_migrations, list_edge_functions. These return structured JSON that Claude can reason over without writing SQL boilerplate first. The agent does not need to query information_schema to understand your schema — the MCP tool handles that.
Auditability. MCP tool calls are logged at the server level. You can see exactly what schema introspection or data queries the agent performed. Raw SQL via a connection string leaves no trace unless you set up your own query logging.
No credentials in prompts. Passing a connection string to an agent means it lives in your conversation context. MCP authentication is handled at the transport layer — the token is never part of the prompt context that gets sent to the model.
That said, if your use case is genuinely read-heavy SQL work — writing complex analytics queries, for example — a direct PostgreSQL MCP connection (a read-only database role + the PostgreSQL MCP server) can complement the Supabase MCP rather than replacing it. See our PostgreSQL MCP server guide for that setup.
Using Supabase MCP Alongside AppHandoff
Supabase MCP gives Claude Code a live view of your database. AppHandoff's MCP server gives it a live view of your API contracts, frontend expectations, mismatch reports, and work in flight. The two servers complement each other at different layers of the stack.
Here is where the combination matters: Supabase can tell Claude what columns exist in your orders table. AppHandoff can tell Claude what your frontend expects the /orders API endpoint to return — and whether the backend implementation matches those expectations. If your orders table recently added a fulfillment_status column but the API contract and frontend types have not been updated, AppHandoff surfaces that mismatch before it causes a production bug.
In practice, an agent working on a database migration will use Supabase MCP to check the current schema, generate and apply the migration, then use AppHandoff MCP to check whether the API contract needs updating to match the schema change and create a handoff ticket for the frontend agent. This is the closed-loop development workflow AppHandoff is designed to enable.
To add AppHandoff to your Claude Code setup alongside Supabase MCP:
claude mcp add apphandoff https://api.apphandoff.com/api/mcp-bot
# Or in .claude/settings.json for project-scoped config:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": ["-y", "@supabase/mcp-server-supabase@latest", "--access-token", "${SUPABASE_ACCESS_TOKEN}"]
},
"apphandoff": {
"type": "http",
"url": "https://api.apphandoff.com/api/mcp-bot"
}
}
}AppHandoff uses OAuth for authentication — Claude Code will prompt you to connect your account on first use. Once connected, you have two MCP servers working in parallel: Supabase for live database context, AppHandoff for project-level coordination. Claude Code discovers and uses both automatically based on the tools each task requires.
Troubleshooting
"Server not found" or tools not appearing. Restart Claude Code after adding the server — it only loads MCP configurations at startup. If the tools still do not appear, run claude mcp list to verify the server was registered, then claude mcp get supabase to check the stored command and arguments.
"Access token invalid" error. Personal access tokens are account-scoped, not project-scoped. Make sure you generated the token at app.supabase.com/account/tokens (not from within a project's settings). If the token was generated correctly, verify it has not been revoked — the token list page shows all active tokens.
Wrong project showing up. If you have multiple Supabase projects and the agent is querying the wrong one, you can scope the server to a specific project by adding --project-id <your-project-ref> to the args array. The project ref is the string in your Supabase project URL.
npx slow on first call. The first time Claude Code starts with the Supabase MCP configured, npx downloads the package. Subsequent starts use the npm cache and are near-instant. If startup latency is a concern, install the package globally (npm install -g @supabase/mcp-server-supabase) and reference the binary directly in the command field instead of using npx.
"No tables found" on a valid project. Confirm the Supabase project is not paused (free-tier projects auto-pause after inactivity). Go to app.supabase.com, open the project, and check the status. Paused projects reject API requests including those from the MCP server.
For additional setup patterns and more MCP servers worth adding, see the best MCP servers for Claude Code hub post.