Setting up the Supabase MCP Server

The Supabase MCP Server is hosted: nothing is installed locally, and the MCP client connects directly to https://mcp.supabase.com/mcp.

Setting it up in Claude Code

claude mcp add --transport http supabase "https://mcp.supabase.com/mcp"

Then run claude /mcp, select "supabase", and confirm "Authenticate". A browser window opens for signing in with your Supabase account.

Scoping access tightly from the start

Rather than full access, most use cases are better served by an immediately scoped configuration:

claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<project-id>&read_only=true"

project_ref binds access to exactly one project and automatically disables account management tools (no creating new projects, no managing organizations). read_only=true forces a read-only database user, so the agent can't apply migrations or modify data. Both parameters can be removed later once the agent proves reliable and write access is genuinely needed.

Setting it up in other clients

The official documentation provides an interactive URL builder: choose the platform, project, desired feature groups, and options, and the page automatically generates the right configuration for Cursor, Windsurf, and other clients.

Local development

Anyone running Supabase locally via the Supabase CLI can reach the MCP server at http://localhost:54321/mcp. This environment offers only a limited tool set, and OAuth 2.1 is not supported — sign-in works differently than with the hosted service.

Choosing feature groups deliberately

The features parameter can further narrow the tool set, for example features=database,docs to enable only database and documentation tools. Storage tools are disabled by default anyway and must be explicitly added via features=storage if needed.

Common connection issues

If OAuth sign-in fails with a project-related error, check whether the project ID given in the project_ref parameter actually exists and that the signed-in account has access to it. In local development via the Supabase CLI, a missing or misconfigured local instance prevents the client from connecting to http://localhost:54321/mcp — checking the CLI logs usually reveals the cause.

Verifying the setup

After connecting, test with a harmless, read-only task, such as "Show me the tables in my project" or "Search Supabase documentation for Row Level Security." Only disable read-only mode once this works reliably and access is scoped to the correct project.

Following this order avoids the most common cause of accidental data changes with a new Supabase MCP connection: write access enabled too early against a production project.

A minute spent testing on the read-only endpoint is far cheaper than restoring a table after an unintended write.

Source: github.com/supabase-community/supabase-mcp and supabase.com/docs/guides/ai-tools/mcp, checked on 2026-09-06.