How to Use Claude × Supabase MCP | Connection Setup and Read-Only Configuration

The Relationship Between Claude and Supabase MCP

Supabase MCP is an MCP server maintained by the official Supabase community. It acts as a bridge for MCP clients like Claude to access Postgres databases, Edge Functions, Storage, and logs. Claude connects as a client via the MCP protocol, translating natural language instructions from the user — such as "how many rows are in the users table?" or "I want to check failed_jobs" — into calls to the tools provided by the server.

There is no dedicated feature on Anthropic's side; Claude reads and uses the tool definitions provided by the MCP server, which is a standard mechanism. This means it works with a common connection configuration in both Claude Desktop and Claude Code, as long as the environment supports MCP client functionality. The recommended flow is to use the host URL https://mcp.supabase.com/mcp via HTTP transport over HTTPS.

Source: Supabase Docs — Model Context Protocol

What You Can Do with Supabase MCP

Supabase MCP organizes its capabilities into 8 tool groups, and you can switch which groups are enabled depending on your use case. The main groups are as follows.

• Database: List tables, execute SQL, apply migrations
• Debugging: Retrieve Postgres logs, check the security advisor and performance advisor
• Development: Get API URLs, retrieve anon/service keys, generate TypeScript types
• Edge Functions: List, retrieve, and deploy functions
• Branching: Create and switch development branches (paid plan required)
• Storage: Check bucket settings (disabled by default)
• Account: Manage projects and organizations (unavailable when project scope is set)
• Knowledge Base: Search official Supabase documentation

When using Claude Code, the most impactful capabilities are SQL execution under Database and TypeScript type generation under Development. You can complete an entire schema-tracking workflow — "modify table → regenerate types → fix client code" — in a single prompt. The Debugging group is practically useful for bug investigations, since you can ask it to "retrieve the last hour of Postgres error logs."

Source: supabase-community/supabase-mcp (GitHub)

Connection Steps

Add a Supabase MCP entry to Claude's MCP configuration file (for Claude Desktop: claude_desktop_config.json; for Claude Code: .mcp.json or ~/.claude/mcp.json). The actual steps proceed in the following order.

1. Log in to the Supabase dashboard, go to Project Settings for your target project, and note down the Project Ref (an ID like abc123xyz).
2. On the "Access Tokens" screen in the same dashboard, issue a personal access token and store it as SUPABASE_ACCESS_TOKEN in a safe location (a .env file or OS keychain is recommended; writing it directly in a repository is strictly prohibited).
3. Open Claude's MCP configuration file and add the following block under mcpServers.

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true",
      "headers": {
        "Authorization": "Bearer YOUR_SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

4. If using Claude Desktop, restart the app. If using Claude Code, open a new session.
5. In Claude's chat, ask "Are you connected to the Supabase MCP?" and confirm that supabase.* tools appear in the tool list.

The key point is passing project_ref and read_only as URL query parameters. Omitting them results in quite broad permissions — write access to all projects — so always explicitly specifying these two during the verification phase is the safe approach.

Why Read-Only Mode Is Recommended

Supabase MCP has a mechanism where adding the URL query read_only=true causes all queries to be executed as a read-only user on the server side, and write SQL such as INSERT / UPDATE / DELETE / DROP is rejected at the Postgres level. The major benefit is that accidental queries — like Claude generating and executing "DELETE FROM users" — are stopped at the database engine layer rather than relying on client-side review.

In particular, when running long agentic tasks with Claude Code, it is not practical to manually go through the tool call approval flow every time. Making read_only=true the default offers a good balance between safety and work speed. Only when writes are needed should you temporarily add a write-enabled MCP entry (with a separate URL and separate token), then remove it after the task is done. This approach minimizes the risk of accidents.

The official documentation explicitly states "avoid direct connections to production projects; use only development projects" and "connecting AI systems to data carries security risks." Given the nature of MCP clients executing arbitrary prompts, a design that suppresses SQL injection-like risks at the database layer is necessary.

Limiting Target Projects with project_ref

Specifying project_ref=<ID> as a URL query parameter fully restricts that MCP connection to the single specified project. Project creation/deletion under the Account group and database operations on other projects are automatically disabled, preventing accidental access to a neighboring test environment.

When you want to switch between multiple projects, the recommended pattern is to add multiple entries under mcpServers with distinct names like supabase_dev / supabase_staging, each assigned a different project_ref. From Claude's perspective, they appear as separate MCP servers, so instructions like "look at the staging users table" or "check the dev migrations" are delivered unambiguously.

Narrowing Down Features with features

The features=<group1>,<group2> query lets you whitelist which tool groups to enable. For example, writing features=database,docs makes only the Database and Knowledge Base tools visible to Claude, physically preventing calls to Edge Functions deployment or Account operations.

If your policy is "I only want Claude to handle DB inspection and official documentation search — deployments should remain with humans and CI" — then combining read_only=true with features=database,docs is a convenient starting point for minimum permissions. When you later decide "I also want to delegate TypeScript type generation," you can simply add development to features, naturally leading to an operation style of expanding access only when needed.

Security and Operational Notes

Since natural language reaches the database through the MCP server, you need to operate with the assumption that unintended operations could run via prompt injection. Supabase officially recommends the following measures.

• Do not connect MCP directly to production projects: Always use a dedicated development or staging project.
• Minimize access token permissions: Do not expose personal tokens in shared chats or CI logs; rotate them regularly.
• Manually approve tool calls: Enable confirmation on the Claude side for critical operations, and always visually verify SQL content.
• Make read-only the default: Only allow writes temporarily via a separate entry.
• Limit targets with project_ref: Do not permanently attach tokens with full project permissions.

These are items explicitly listed as "security recommendations" in the official documentation. Even teams prioritizing development speed should address at least these points, or they are likely to receive feedback during PR reviews asking "why is this configured to connect directly to the production DB?" To safely capture the benefits of AI integration, it is well worth building in these guards from the moment you write your initial .mcp.json.

Summary

The practical way to get started with Claude × Supabase MCP can be distilled into a minimal setup: (1) note down your personal access token and Project Ref, (2) write a URL with read_only=true and project_ref into claude_desktop_config.json or .mcp.json, and (3) whitelist only the tool groups you need via features. By keeping writes on a separate entry with a separate token, opened only temporarily, you can delegate schema-tracking and investigation tasks to Claude while structurally avoiding production accidents.

Sources:

• Supabase Docs — Model Context Protocol
• supabase-community/supabase-mcp (GitHub)