Merge Unified's Supabase integration Merge Agent Handler's Supabase MCP server

Connect your AI Agents to Supabase in minutes

Merge lets you securely connect your agents to Supabase and thousands of tools instantly

Start building for free

Read docs

Supabase

Learn more about Merge Agent Handler

Available tools

list_api_keys

List all API keys for a Supabase project. Use list_projects to find project refs.

create_api_key

Create a new API key for a Supabase project. Name must be lowercase alphanumeric/underscores only (e.g. 'mykey'). Use listprojects to find project refs.

get_api_key

Get details of a specific API key. Use listapikeys to find key IDs.

update_api_key

Update an API key's name or description. Name must be lowercase alphanumeric/underscores only. Use listapikeys to find key IDs.

delete_api_key

Delete an API key from a Supabase project. Use listapikeys to find key IDs.

get_auth_config

Get the auth configuration for a Supabase project. Includes email/phone settings, JWT config, and signup rules.

update_auth_config

Update auth configuration for a Supabase project. Supports email/phone toggles, JWT expiry, signup, and token rotation.

list_branches

List all database branches for a Supabase project. Requires branching to be enabled. Use list_projects to find refs.

create_branch

Create a new database branch for a Supabase project. Requires branching to be enabled on the project.

get_branch_by_name

Get a database branch by name. Use list_branches to find branch names.

get_branch

Get details of a database branch by ID. Use list_branches to find branch IDs.

update_branch

Update a database branch's name or git branch association. Use list_branches to find IDs.

delete_branch

Delete a database branch. This is irreversible. Use list_branches to find IDs.

delete_all_branches

Delete all database branches for a project. This is irreversible. Disables branching.

push_branch

Push a database branch's migrations to the parent project. Use list_branches to find IDs.

merge_branch

Merge a database branch into the parent project. Use list_branches to find IDs.

reset_branch

Reset a database branch to match the parent project's schema. Use list_branches to find IDs.

diff_branch

Get the SQL diff between a database branch and its parent project. Use list_branches to find IDs.

execute_query

Execute a SQL query against a Supabase project's database. Supports DDL (CREATE TABLE, ALTER) and DML (SELECT, INSERT, UPDATE, DELETE). Use list_projects to find refs.

list_edge_functions

List all edge functions for a Supabase project. Use list_projects to find project refs.

create_edge_function

Create a new edge function in a Supabase project. Use list_projects to find project refs.

get_edge_function

Get details of an edge function. Use listedgefunctions to find function slugs.

update_edge_function

Update an edge function's name, body, or JWT settings. Use listedgefunctions to find slugs.

delete_edge_function

Delete an edge function from a Supabase project. Use listedgefunctions to find slugs.

list_migrations

List database migration history for a Supabase project. Use list_projects to find refs.

create_migration

Create and execute a database migration for a Supabase project. Rolls back on failure. Use list_projects to find refs.

list_organizations

List all organizations the authenticated user belongs to.

create_organization

Create a new Supabase organization.

list_organization_members

List members of a Supabase organization. Use list_organizations to find the organization slug.

list_projects

List all Supabase projects the authenticated user has access to.

create_project

Create a new Supabase project in an organization. Use list_organizations to find organization IDs.

get_project

Get details of a Supabase project by its reference ID. Use list_projects to find project refs.

update_project

Update a Supabase project's name. Use list_projects to find project refs.

delete_project

Delete a Supabase project. This is irreversible. Use list_projects to find project refs.

pause_project

Pause a Supabase project. Paused projects stop incurring compute costs. Use list_projects to find refs.

restore_project

Restore a paused Supabase project. Use list_projects to find project refs.

get_project_health

Get health status of a Supabase project's services. Use list_projects to find project refs.

list_secrets

List all secrets for a Supabase project. Secret values may be redacted. Use list_projects to find refs.

create_secrets

Create or update secrets for a Supabase project (bulk). Each secret needs 'name' and 'value'.

delete_secrets

Delete secrets from a Supabase project by name (bulk). Use list_secrets to find secret names.

list_snippets

List all SQL snippets accessible to the authenticated user.

get_snippet

Get a SQL snippet's details and content by ID. Use list_snippets to find snippet IDs.

validate_credential

Validate Supabase credentials by making a test API call. Returns success status and message.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Supabase MCP server

What is a Supabase MCP?

It's an MCP server that lets your agents interact directly with Supabase's backend platform via tools. Your agents can invoke these tools to run SQL queries, manage database migrations, deploy edge functions, configure project settings, and more.

Supabase offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Supabase MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Automated schema migrations on merge: When a feature branch is merged in GitHub, an agent generates the corresponding Supabase migration, applies it to the staging database branch, and posts a schema diff to the pull request for review before it goes to production

Database-driven product reporting: On a weekly schedule, an agent runs SQL queries against a Supabase database to aggregate retention, usage, or revenue metrics, formats the results into a readable summary, and posts them to the product team's Slack channel

Project provisioning for new clients: When a new client engagement is created in a project management tool, an agent creates a Supabase project, applies the baseline schema, and stores the required API credentials as project secrets, ready for the dev team to use

Edge function deployment on config change: When a configuration file is updated in a GitHub repository, an agent redeploys the affected Supabase edge function with the new code and confirms the deployment succeeded before closing the PR

What are popular tools for Supabase's MCP server?

Here are some of the most commonly used tools:

execute_query: runs a SQL statement against a Supabase Postgres database and returns the results. Use this when an agent needs to read, insert, update, or delete data as part of any data-driven workflow

create_migration: generates and applies a new database migration to a Supabase project or branch. Good for workflows where schema changes need to be versioned and applied in response to a code or deployment event

list_projects: returns all Supabase projects in the account along with their status and configuration metadata. Helpful when an agent needs to identify the correct project before running queries or applying changes

get_project_health: checks the health status of a specific project, including database and API availability. Call this when an agent needs to confirm a project is operational before executing operations or after a deployment completes

create_edge_function: deploys a new edge function to a Supabase project with a specified name and code payload. Use this when an agent is provisioning serverless logic as part of a project setup or an automated release workflow

create_secrets: stores environment secrets against a Supabase project, making them accessible to edge functions and server-side code. Use this when an agent is bootstrapping a new project and needs to configure third-party credentials without exposing them in source code

What makes Merge Agent Handler's Supabase MCP server better than alternative Supabase MCP servers?

Supabase has its own official MCP server, but there are good reasons to run Supabase through Merge Agent Handler in production environments:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Supabase, this means you can prevent database contents, API keys, auth configuration, and project secrets from being exposed even when the agent has broad access to the platform

Managed authentication and credentials: Merge stores and manages your Supabase credentials on your behalf. You never inject service role keys or OAuth tokens directly into agent configuration, and you don't need to handle re-authentication as credentials change

Real-time observability and audit trail: Every tool call against Supabase is logged: which query ran, which project was targeted, what the response contained. That record is searchable and available to your engineering and security teams without any custom instrumentation

Tool Packs and controlled access: Tool Packs let you bundle specific Supabase tools with tools from other connectors into a single MCP endpoint, scoped to a specific use case. An agent gets exactly the tools it needs, nothing more

How can I start using Merge Agent Handler's Supabase MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account and navigate to Tool Packs (collections of connector tools scoped to a specific use case).

2. Create a new Tool Pack, then find and enable the Supabase connector. Choose the tools that fit your workflow: execute_query and list_projects cover most read and reporting use cases, while create_migration, create_edge_function, and create_secrets are needed for agents that provision or modify infrastructure.

3. Add a Registered User inside the Tool Pack. This is the identity context under which your agent operates. Merge generates a unique MCP URL scoped to this user once it's created.

4. From the Registered User detail page, authenticate Supabase by completing the OAuth flow. Merge stores and manages the credentials going forward.

5. Copy the MCP URL from the Tool Pack detail page and generate an API key from Settings. You'll need both to connect your agent.

6. Add the MCP server to your agent or IDE using the MCP URL and API key. Your Supabase tools are now accessible through that endpoint.