How to connect to the Supabase MCP with Claude Code (5 steps)

Developers building on Supabase spend a significant amount of time context-switching: checking table schemas in the dashboard, running queries to debug data issues, verifying auth configurations, then switching back to the terminal to write the next line of code.

To help developers query and manage their Supabase projects without leaving the terminal, we’ll show you how to connect Supabase with Merge Agent Handler’s Supabase MCP server.

How it works

Merge Agent Handler acts as a secure bridge between Claude Code and Supabase’s API. 

When you configure a Tool Pack and Registered User, Merge generates a unique MCP URL that Claude Code accesses via HTTP, combined with an API key for authentication.

Here’s how the command looks (we’ll walk through getting your MCP URL and API key in the following steps):

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

Claude Code sends requests to that MCP URL, and Merge handles authentication and API calls to Supabase on the backend. You don’t manage Supabase credentials locally or embed them into your codebase. Merge handles credential storage and token management from here on.

Prerequisites

Before getting started, you’ll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude –version to confirm)
• A Supabase account with access to the project you want to connect

Related: A guide to integrating the Figma MCP with Claude Code

1. Create a Tool Pack

Log into Merge Agent Handler and navigate to Tool Packs. Click Create Tool Pack and give it a name tied to the use case, like Supabase DB Agent.

Under connectors, select Supabase, and choose which tools to enable. 

For most development workflows, enabling table listing, schema inspection, and row querying covers the common cases. Enable write tools if you want your agent to insert or update records.

Save the Tool Pack. You’ll return here in step 4 to copy your MCP URL.

2. Add a Registered User

Inside your Tool Pack, create a Registered User. This is the identity context under which your agent operates.

Give it a name that maps to your environment, like <code class="blog_inline-code">dev-local</code> or your own name. Once created, Merge generates a unique MCP URL scoped to this user.

‍

3. Authenticate Supabase

From the Registered User detail page, click Add Connector and select Supabase.

Complete the authentication flow to grant your agent access to the Supabase project you want to connect. 

Once authenticated, Merge stores and manages the credentials. You won’t need to re-authenticate unless you revoke access.

4. Gather your credentials

You need two things before configuring Claude Code:

1. MCP URL: found on the Tool Pack detail page under the Registered User you just created. It looks like the following: <code class="blog_inline-code">https://ah-api.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp</code>

2. API key: found in Settings > API Keys in your Merge Agent Handler dashboard. Create one if you don’t have one yet.

Keep both handy for the next step.

5. Configure Claude Code with Supabase

Run the following command in your terminal, substituting your actual MCP URL and API key:

 {
 "mcpServers": {
   "agent-handler": {
     "command": "npx",
     "args": [
       "-y",
       "mcp-remote@latest",
       "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
       "--header",
       "Authorization: Bearer ${AUTH_TOKEN}"
     ],
     "env": {
       "AUTH_TOKEN": "yMt*****"
     }
   }
 }
}

Verify the connection registered: <code class="blog_inline-code">claude mcp list</code>

<code class="blog_inline-code">agent-handler</code> should appear in the output with a connected status.

To confirm the connector is accessible, open a Claude Code session and run something like, "List all tables in my Supabase database and show me the schema for the users table." You should see an output like the following:

{{this-blog-only-cta}}

Supabase MCP FAQ

In case you have more questions on setting up and using the Supabase MCP in Claude Code, we’ve addressed several more commonly-asked questions below.

What can you do once the Supabase MCP is connected to Claude Code?

With Supabase connected, Claude Code can:

• List and inspect tables: retrieve the full schema for any table in your database, including column types, indexes, and constraints

• Query rows: run read queries against your Supabase tables and return results Claude can reason over directly in the terminal

• Check auth configuration: inspect your project’s authentication settings, enabled providers, and user records without opening the dashboard

• Browse storage buckets: list files and folders in Supabase Storage to verify upload state or locate assets

• Read Edge Function logs: surface recent invocations and errors from your deployed Supabase Edge Functions

Why use Merge Agent Handler vs. a self-hosted Supabase MCP server?

You can run a self-hosted MCP server that connects directly to Supabase. For a solo project with a single environment, that works fine.

It breaks down when you need to scale. Self-hosting means managing Supabase credentials locally, handling credential rotation, and maintaining the server as Supabase’s API changes. For teams where multiple developers need access to the same project, you end up coordinating credentials out-of-band, which creates security surface and operational overhead that compounds over time.

Merge Agent Handler is a managed MCP layer. It centralizes authentication, scopes access at the Tool Pack and Registered User level so each developer or agent gets exactly the permissions they need, and adds observability over every tool call. When you need to audit what an agent queried or modified, the logs are there.

For anything beyond a one-off prototype, Merge Agent Handler removes the infrastructure burden so you can focus on the agent logic rather than the plumbing.

Why connect Supabase to Claude Code?

Supabase is where your application data lives. Claude Code is where you write the code that works with it. Keeping them disconnected means constant context-switching: check the schema in the dashboard, copy it somewhere, reason about it in your editor, then switch back to test. That loop is slow.

With the Supabase MCP connected, Claude Code can inspect table schemas, run queries, and check auth configurations directly in the terminal. That means fewer browser tabs, fewer copy-paste cycles, and a tighter feedback loop when you’re debugging data issues or evolving a schema.