Claude Code Add MCP Supabase
Add Supabase MCP to Claude Code, authenticate with OAuth, scope one development project, and verify its tools with a read-only request.
TL;DR
Connect Claude Code to Supabase's official remote HTTP endpoint and complete browser-based OAuth instead of creating a personal access token for normal interactive use.
Bind the URL to one development project, turn on read-only mode first, and expose only the feature groups needed for the task.
Confirm server health and tool visibility, then inspect tables or documentation before requesting SQL, migrations, function deployment, or branching operations.
Database rows and logs can contain prompt injection. Review tool names, parameters, SQL, target project, and expected effect before every consequential call.
The safe default is a project-scoped connection to a development environment with read_only=true and a small features list. Authenticate in a regular terminal, reload Claude Code, inspect the server and its tools, and run a read-only metadata request. Supabase explicitly describes its MCP server as a development and testing tool; do not connect it to production data simply because setup is easier.
Prepare Claude Code and Supabase first
Open the repository that should own the MCP configuration, update Claude Code, and select a Supabase development project containing only synthetic, test, or properly obfuscated data. Record its project reference from the Supabase dashboard. Project scope is useful when a team wants the server definition in .mcp.json, but every teammate must still review that shared configuration and authenticate with an appropriate Supabase account.
Use a disposable project or development branch. Do not point the first connection at production, customer data, payment records, authentication tables, or another sensitive environment.
docs supports documentation search; database covers tables, SQL, and migrations; debugging exposes logs and advisors; development covers project URL, keys, and type generation. Leave functions, branching, account, and storage disabled unless the task needs them.
Plan one harmless request such as listing table names or searching documentation. Write down the expected project reference and schemas so an empty or surprising response can be identified immediately.
The current Supabase MCP guide is the source of truth for endpoint options and tool groups. Supabase changes quickly, so regenerate the command from its configuration panel when revisiting the setup rather than copying an old URL from a blog post.
Add the Supabase MCP server to Claude Code
For the official hosted server, use remote HTTP transport. Replace YOUR_PROJECT_REF with the development project reference and begin with a narrow feature set. The following example permits documentation, database inspection, debugging, and development helpers while making database queries read-only:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true&features=docs,database,debugging,development"
Confirm the host is exactly mcp.supabase.com, the project reference matches the intended development project, read_only=true is present, and the feature list contains no unnecessary group. Project scoping also disables account-management tools.
Run the command from the repository root. Project scope creates a team-shareable definition, so inspect the resulting .mcp.json before committing it. The URL may identify a project, but it must not contain a personal access token.
Start Claude Code, run /mcp, choose supabase, select Authenticate, and finish the browser flow with the organization that owns the selected project. A personal access token is no longer required for normal hosted authentication.
Restart or reload the Claude Code session if tools do not appear after authorization. Then use claude mcp list, claude mcp get supabase, and /mcp to confirm configuration, status, and authentication.
When manual credentials are justified
Manual authentication is mainly for non-interactive CI or clients that cannot complete dynamic OAuth registration. In CI, use a purpose-specific personal access token with the necessary scopes, inject it as an environment secret, and reference it through an authorization header. Never commit the token to .mcp.json, shell history, screenshots, or documentation. Keep CI attached only to isolated development resources and rotate the token when the job or owner changes.
Verify the connection before real work
| Check | Expected evidence | If it fails |
|---|---|---|
| Registration | claude mcp get supabase shows HTTP transport and the reviewed URL. | Check repository root, scope, name, and .mcp.json. |
| Reachability | The endpoint responds and Claude reports an authentication state rather than a startup failure. | Check proxy, TLS inspection, DNS, firewall, and service status. |
| Authorization | /mcp reports Supabase connected under the intended organization. | Repeat OAuth in a regular terminal and reload the session. |
| Scope | Only the intended project and selected feature groups are available. | Compare project_ref, features, and current account permissions. |
| Smoke test | A table-list or documentation request returns the expected project context without mutation. | Check schema, branch, role, read-only mode, and tool arguments. |
Have Claude state the server name, project context, enabled feature groups, and whether the connection is read-only. This makes an accidental organization or project mismatch visible before any query.
Ask for table names in a known schema or search the official documentation for a specific topic. Compare the result with the dashboard rather than accepting a plausible answer.
Before any SQL or migration call, ask Claude to show the selected tool and arguments. Review identifiers, query text, project, and whether the operation can write or deploy.
Move from inspection to schema work deliberately
When read-only verification passes, do not simply remove the flag and ask for a broad feature. First have Claude explain the desired schema change, produce the SQL or migration plan, identify dependencies and rollback steps, and stop for review. Apply approved changes only to a disposable project or development branch. Afterwards, inspect the migration history, run security and performance advisors, execute focused tests, and compare the resulting schema with the plan before merging through the team's normal database workflow.
Keep Supabase MCP access safe
MCP makes database tools easier for an agent to invoke; it does not turn developer-level access into a safe end-user API. The Supabase server operates with the authenticated developer's permissions, so application RLS and UI restrictions should not be assumed to contain every MCP action. Do not expose this integration to customers or let an unattended agent use it as a backend for user requests.
Rows, logs, function source, issue text, and imported content may include instructions aimed at the model. Treat them as data, not commands. Keep manual approval on and reject tool calls whose purpose changed after reading external content.
read_only=true prevents database writes through the read-only Postgres role, but readable sensitive data can still be exposed in model context or output. Use only non-production or obfuscated data and restrict schemas through the project design.
Project scoping limits which project is reachable; feature groups limit which classes of tools are visible. Use both. Remove functions, branching, storage, account, or debugging groups when the current task does not require them.
Record who authorized the connection, the reviewed configuration, prompts, selected tools, parameters, SQL, approvals, results, migrations, and affected environment. Rotate any token that appears in source control, logs, chat, or screenshots.
Use QVeris when the agent needs more than Supabase
Supabase MCP gives Claude Code a focused path into one backend platform. A live search of the QVeris Tool and Provider directories found no exact Supabase record, so this page links to QVeris Docs and the Playground instead of claiming a direct catalog integration.
- Keep schema inspection, SQL review, migrations, logs, advisors, and project-specific operations inside the official Supabase MCP boundary.
- Use QVeris only for a separate external capability returned by current discovery, then inspect its provider, schema, constraints, and cost before calling it.
- Validate external results before writing them to Supabase, and require human approval at the boundary between external data and database mutation.
FAQ
Not for normal interactive hosted setup. Supabase uses browser-based OAuth with dynamic client registration. A PAT is mainly for non-interactive CI and must stay in a secret store.
Usually no. Use the current command generated by Supabase. Project scope creates .mcp.json; review that file before sharing it, but do not add credentials to it.
Confirm the endpoint responds, complete OAuth from a regular terminal, verify the selected organization, and reload Claude Code. Then inspect status with /mcp.
The features parameter may exclude their group, storage is disabled by default, project scope disables account tools, or the client may need a restart after authorization.
No. It reduces database writes but does not prevent sensitive reads, prompt injection, or disclosure through model context. Supabase recommends development and testing projects instead.
First produce and review a plan, SQL, dependencies, rollback, and target environment. Remove read-only only for an isolated development branch, approve each mutation, test, and merge normally.
References and next steps
Supabase MCP guide
Supabase MCP repository
Claude Code MCP documentation