How to Add Supabase MCP to Claude Code

Update Claude Code, open the repository root, and copy the development project's reference from Supabase. Verify that the project contains no production or unredacted customer data. Decide whether the team needs project scope or whether local is safer for evaluation.

Select the project, enable read-only, and start with database,docs. The result should use https://mcp.supabase.com/mcp with project_ref, read_only=true, and a short features query. Project binding also removes account-management tools.

Run claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true&features=database,docs". Replace the placeholder, and change only the scope if the earlier decision calls for local or user configuration.

Start Claude Code from a regular terminal, enter /mcp, choose supabase, and select Authenticate. Sign in to the organization that owns the selected project. Normal interactive use relies on OAuth and does not require a personal access token.

Project-scoped servers may require workspace trust and explicit approval because the definition comes from the repository. Review the URL before approving it. Reload the session if authorization succeeds but the selected tools have not appeared.

Run the command from the intended repository, verify the scope and server name, inspect .mcp.json for project scope, and reload Claude Code. A configuration created elsewhere will not automatically apply here.

Confirm the URL host and transport, check proxy or firewall restrictions, then repeat authentication from a regular terminal. Do not replace OAuth with a pasted token merely to bypass a browser problem.

Inspect the features parameter. Storage is disabled by default, project-scoped mode excludes account management, and a client may need a reload after authorization or configuration changes.

Recheck the project reference, selected organization, database branch, schema, and account permissions. Stop if unfamiliar schemas or sensitive data appear; do not “test” by writing a marker row.

A URL without project_ref may expose every project the authenticated account can access, while project-scoped mode disables account-management tools. Add features=database,docs or an even smaller list instead of enabling every group by default.

read_only=true runs database queries as a read-only Postgres user. Supabase also advises using this MCP server for development and testing, not production data.

Database content can contain prompt-injection instructions. Review every tool call and SQL statement before approval; Supabase's protective wrapping reduces risk but is not foolproof.

Read-only prevents database mutation through its restricted role, but it cannot stop sensitive rows from entering model context or output. Use development data, minimize schemas and feature groups, and keep customer or authentication records out of the test project.

When writes are eventually required, first ask for a migration plan, generated SQL, affected objects, rollback, and tests. Apply approved work to an isolated branch, run database advisors, inspect the diff, and merge through the team's normal process.