Exposing Supabase to your agent via MCP

The MCP (Model Context Protocol) lets Claude Code connect to external tools and use them directly in your conversations. Supabase provides an official MCP server that exposes your database, Edge Functions, auth, and many other resources to your agent. This lesson walks you through generating the token all the way to running your first test in the terminal.

Generating a personal access token

The Supabase MCP server authenticates with a personal access token tied to your Supabase account, not to a specific project. A single token is enough to access all your projects.

1. Open the Supabase dashboard, click your avatar at the bottom left, then go to Account > Access Tokens.
2. Click Generate new token.
3. Give it a clear name, for example claude-code-mcp.
4. Copy the token immediately: it will not be displayed again after you close the window.

Adding the MCP server to Claude Code

The Supabase MCP server runs in HTTP mode: it lives on Supabase's servers at https://mcp.supabase.com/mcp. You do not need to install anything locally. You simply tell Claude Code where to find it and how to authenticate.

Via the CLI command (recommended)

$claude mcp add --transport http supabase https://mcp.supabase.com/mcp --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace YOUR_ACCESS_TOKEN with the token you just generated. The command registers the server in your Claude Code configuration at the local scope (default, specific to your user on this machine).

Via a .mcp.json file (to share the config with your team)

If you are working on a versioned project and want the whole team to benefit from the MCP server, create a .mcp.json file at the root of the project:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

The ${SUPABASE_ACCESS_TOKEN} notation is resolved automatically from your shell environment variables. Each team member exports their own variable, and the token never passes through the repository.

Verifying the connection

Once the server is added, verify that Claude Code recognizes it.

$claude mcp list

You should see supabase in the list with its URL. To go further, launch Claude Code and type /mcp: the command shows the real-time status of each server (connected, pending, or error) and the number of available tools.

Testing with a first query

Launch Claude Code in your terminal, then ask a question that requires querying your Supabase database.

$claude

Once in the chat interface, try this prompt:

List the tables in my Supabase project and describe their structure.

If several projects are associated with your account, Claude Code will ask which one to use. You can also target a specific project from the start by appending ?project_ref=YOUR_PROJECT_REF to the MCP server URL in your configuration.

What the MCP server can do

The server exposes several tool groups enabled by default:

• Database: list tables and extensions, read the migration log, execute arbitrary SQL.
• Development: retrieve the API URL, public keys, generate TypeScript types.
• Edge Functions: list, inspect, and deploy your functions.
• Debugging: view service logs and security advisors.
• Docs: search the Supabase documentation directly from the agent.

The Storage group is disabled by default. The Branching group requires a paid plan.