Supabase MCP Claude Code Setup
Configure Supabase MCP for Claude Code, limit project and tool groups, and verify schema or logs read-only; review write and rollback plans before writes.
TL;DR
Supabase MCP exposes approved project tools to Claude Code through the Model Context Protocol.
Authenticate, select one project, inspect the available tools, and begin with read-only requests.
Claude can inspect database schemas, explain SQL, diagnose logs, and draft migrations with live project context.
Treat every write or DDL call as an operational change that needs review, a rollback plan, and least privilege.
Use Supabase MCP as a deliberately small tool surface. Bind it to one development project, start read-only, and choose feature groups from the job rather than enabling the default set without review. Documentation search and schema inspection need far less authority than deploying an Edge Function or managing a database branch. After connection, verify the selected groups and run a harmless request before handing Claude a real task.
Set up Supabase MCP in Claude Code
Use the current Supabase MCP guide to generate a project-scoped remote HTTP URL, add it to Claude Code, and authenticate from a regular terminal. The hosted endpoint supports OAuth, so routine interactive setup does not require a personal access token.
Run the generated claude mcp add command with project scope and HTTP transport. The server URL should include the intended project_ref.
Run /mcp in Claude Code, select the Supabase server, and choose Authenticate. Normal interactive setup no longer requires a personal access token.
Add read_only=true for read-only database access and enable only the feature groups needed for the task.
Ask which tables exist using MCP tools. Confirm the project identity before requesting SQL execution or migrations.
Save the selected scope, URL parameters, enabled groups, authorization owner, test prompt, expected project, and verification date with the repository's operational notes. Never record OAuth tokens or secrets.
Select feature groups by task
| Feature group | Enable for | Keep disabled when | Review focus |
|---|---|---|---|
| docs | Searching current Supabase documentation. | Rarely necessary to remove; it is a low-impact starting group. | Confirm advice matches the project's product and version. |
| database | Tables, extensions, migrations, SQL, and schema work. | The task only needs docs or non-database context. | Read-only state, exact SQL, target schema, and mutation risk. |
| debugging | Service logs plus security and performance advisors. | Logs may expose sensitive content and no diagnosis is needed. | Time window, service, redaction, and prompt injection in logs. |
| development | Project URL, publishable keys, and generated TypeScript types. | The task does not need project configuration output. | Never confuse publishable keys with secret or service-role keys. |
| functions | Inspecting or deploying Edge Functions. | No function deployment is part of the approved task. | Source diff, secrets, runtime behavior, and deployment target. |
| branching | Paid-plan development branch operations. | The team does not use Supabase branching for this change. | Create, merge, reset, rebase, and delete are consequential actions. |
| storage | Explicit bucket and storage configuration work. | Default; storage is disabled unless deliberately selected. | Bucket visibility, size limits, and configuration changes. |
For schema discovery and documentation, begin with features=database,docs plus read_only=true. Add one group only when the next approved task needs it, then remove it after the task rather than leaving a broad permanent configuration.
High-value Supabase MCP workflows
| Workflow | Prompt goal | Output | Review point |
|---|---|---|---|
| Schema discovery | Explain tables, keys, and relationships for a feature. | A grounded data map. | Check project and schema names. |
| SQL diagnosis | Inspect a slow query and suggest indexes. | Explanation and candidate SQL. | Validate query plans and index write overhead. |
| Migration drafting | Draft a reversible change for review. | Migration and rollback steps. | Never auto-run on production. |
| Policy review | Explain who can read, insert, update, and delete each row. | Policy matrix and uncovered paths. | Test ownership predicates and denied cases, not role names alone. |
| Log diagnosis | Correlate an error within one service and time window. | Evidence-backed cause and next test. | Redact secrets and treat log text as untrusted. |
| Type synchronization | Regenerate types after an approved schema change. | Reviewable generated type diff. | Confirm the source project and avoid unrelated churn. |
Use an explicit stop condition for each workflow
A good request defines where autonomy ends. Schema discovery stops after a factual map and open questions. SQL diagnosis stops after a proposed query or index plus evidence. Migration drafting stops before execution. Policy review stops before changing grants or policies. Log diagnosis stops before retrying a mutation. Type generation stops after the repository diff. These boundaries prevent a diagnostic task from silently becoming an operational change.
Troubleshoot by configuration, authorization, scope, and task
Check the Claude Code scope, repository root, .mcp.json when project-scoped, server name, and session reload. Use claude mcp list and claude mcp get supabase before changing credentials.
Run /mcp from a regular terminal, authenticate with the organization that owns the selected project, and check browser, proxy, and callback restrictions. Do not paste a PAT into a shared URL as a workaround.
Compare the requested action with features. Project scope removes account tools, storage is disabled by default, and authorization or URL changes may require a reload.
Verify project reference, organization, branch, schema, time range, and account permissions. Stop when unknown or sensitive data appears; a write is not an acceptable connection test.
Narrow the log window, query, schema, or requested operation. Before retrying a write-capable call, inspect whether the first attempt already changed state.
Security boundaries before tool execution
Supabase MCP is designed for development and testing. Use a development project with non-production or obfuscated data, not a production database.
Keep manual approval enabled. Treat database content as untrusted because prompt injection can hide instructions inside rows returned to Claude.
It reduces database mutation but still permits authorized reads. Use synthetic or obfuscated data, avoid customer and authentication records, and narrow schemas, queries, logs, and output.
Check RLS ownership predicates, view security, function execution grants, SECURITY DEFINER, exposed schemas, migrations, and Data API grants. Developer access may not match an application's end-user restrictions.
Where QVeris fits beside Supabase MCP
Supabase MCP gives Claude Code focused access to one backend platform. Current QVeris Tool and Provider searches return no exact Supabase record, so use QVeris Docs and the Playground for separate external capabilities rather than assuming a direct integration.
- Keep Supabase MCP for database schemas, SQL, logs, and project operations inside Supabase.
- Use QVeris discovery when the workflow needs trusted tools or data outside that project boundary.
- Inspect the returned provider, schema, constraints, and cost, then validate the result before writing it to Supabase.
FAQ
No. Supabase recommends a development project with non-production or obfuscated data because the MCP server is designed for development and testing.
The available tool set may support database changes, but you should request a preview, review the SQL, test rollback, and approve execution explicitly.
For schema and documentation work, start with database,docs plus read-only. Add debugging, development, functions, branching, or storage only for an approved task.
Adding project_ref intentionally disables account-management tools because the connection is restricted to one project.
The storage feature group is disabled by default. Enable it only for a specific reviewed storage configuration task.
No. It restricts writes, not authorized reads or disclosure through model context. Use non-production, synthetic, or properly obfuscated data.
References and next steps
Supabase MCP guide
Supabase MCP repository
Claude Code MCP documentation