Connect Supabase to Claude: Deploy Functions and Control Branches

If you need to connect Supabase to Claude to deploy Edge Functions, manage Postgres database branches, or run administrative SQL queries, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and the Supabase Management API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Supabase to ChatGPT or explore our broader architectural overview on connecting Supabase to AI Agents.

Giving a Large Language Model (LLM) access to your backend infrastructure is a significant engineering challenge. You have to handle OAuth 2.0 token lifecycles, accurately map complex JSON schemas to MCP tool definitions, and deal with Supabase-specific state management. Every time an endpoint updates, you have to rewrite your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Supabase, connect it natively to Claude, and execute complex infrastructure workflows using natural language.

The Engineering Reality of the Supabase API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against cloud infrastructure APIs is difficult.

If you decide to build a custom MCP server for Supabase, you own the entire API lifecycle. Here are the specific challenges you will face:

The Project Reference (ref) Context Trap Almost every actionable endpoint in the Supabase Management API requires a project ref - a 20-character lowercase string that uniquely identifies the project. If you expose raw endpoints to an LLM without strict schema definitions, the model will hallucinate ref strings, attempt to use project names instead of IDs, or lose track of the ref across a multi-step workflow. Your MCP tool definitions must explicitly require this parameter and define its exact formatting constraints so the LLM understands it must fetch the ref first before attempting any database operations.

Asynchronous Branching and Deployments Operations like creating a database branch or deploying an Edge Function are not instantaneous. They return a workflow_run_id or an initial status that must be polled. If you do not construct your MCP tools to handle async polling or instruct the LLM on how to check action statuses, your AI agent will assume the operation completed immediately and fail on subsequent steps (like trying to run a SQL query against a branch that is still spinning up).

Rate Limits and 429 Handling Supabase enforces rate limits on its Management API to prevent abuse. Truto does not retry, throttle, or apply backoff on rate limit errors. When the Supabase API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - in this case, Claude or your agent framework - is entirely responsible for reading these headers, waiting, and implementing its own retry and backoff logic.

Instead of building a custom server to handle schema mapping and authentication, you can use Truto. Truto normalizes authentication and pagination, exposing Supabase endpoints as ready-to-use MCP tools.

How to Generate a Supabase MCP Server with Truto

Truto dynamically generates MCP tools from the integration's resource definitions and documentation. You can generate a Supabase MCP server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

1. Navigate to the Integrated Accounts page for your Supabase connection in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., restrict to read-only methods, filter by specific tags, set an expiration date).
5. Copy the generated MCP server URL. This URL contains a cryptographic token that securely identifies the account - no additional authentication is required unless you explicitly enable API token enforcement.

Method 2: Via the API

For teams embedding AI capabilities into their own products, or provisioning temporary access for CI/CD agents, you can generate MCP servers programmatically.

Send a POST request to /integrated-account/:id/mcp with your desired configuration:

curl -X POST https://api.truto.one/integrated-account/<SUPABASE_ACCOUNT_ID>/mcp \
  -H "Authorization: Bearer <YOUR_TRUTO_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Supabase CI/CD Server",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API returns a secure URL that you can immediately pass to your MCP client:

{
  "id": "mcp_abc123",
  "name": "Supabase CI/CD Server",
  "config": { "methods": ["read", "write"] },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/t_5f8a9b2c..."
}

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to Claude using either the visual interface or a configuration file.

Method 1: Via the Claude UI

1. Open the Claude application.
2. Navigate to Settings -> Integrations.
3. Click Add MCP Server (or "Add custom connector" depending on your version).
4. Paste the Truto MCP URL into the Server URL field and click Add.

Claude will immediately ping the endpoint, perform the handshake, and load the available Supabase tools into its context window.

Method 2: Via Manual Configuration File

If you are using Claude Desktop and prefer manual configuration, you can edit the claude_desktop_config.json file. Truto's managed MCP servers operate over HTTP, so you use the official @modelcontextprotocol/server-sse package to handle the Server-Sent Events (SSE) transport.

Add the following to your configuration file:

{
  "mcpServers": {
    "supabase-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<YOUR_TRUTO_TOKEN>"
      ]
    }
  }
}

Restart Claude Desktop. The Supabase integration is now active.

Security and Access Control

Giving an LLM direct access to your infrastructure is risky. Truto provides four mechanisms to lock down your Supabase MCP server:

• Method Filtering (config.methods): Restrict the server to specific operation types. Set ["read"] to allow get and list operations while blocking create, update, and delete. This is ideal for analytics agents that should never modify database schemas.
• Tag Filtering (config.tags): Scope the server to specific functional areas. For example, pass ["database"] to allow SQL querying and branching tools, but block access to "auth" tools that manage users.
• API Token Enforcement (require_api_token_auth): By default, the MCP URL acts as a bearer token. If you set this flag to true, the MCP client must also pass a valid Truto API token in the Authorization header, adding a second layer of authentication.
• Expiration (expires_at): Set a strict time-to-live for the server. Once the timestamp passes, Truto automatically deletes the token and terminates access. This is perfect for granting temporary debugging access to an agent.

Hero Tools for Supabase Automation

Truto automatically generates descriptive, heavily-typed tools for Claude based on the Supabase integration schema. Here are the highest-leverage tools available for your AI agents.

1. List All Supabase Projects

Tool Name: list_all_supabase_projects

Before Claude can execute commands on a specific database, it needs the 20-character project reference (ref). This tool lists all projects the authenticated user can access, returning critical metadata like the ref, region, and status.

"Fetch a list of all my Supabase projects. Find the one named 'production-backend' and save its project reference string for the next steps."

2. Create a Database Branch

Tool Name: create_a_supabase_project_branch

Allows Claude to safely spin up a database branch before executing potentially destructive SQL migrations. The agent passes the ref and a branch_name.

"Create a new database branch called 'feature-add-users-table' on the 'production-backend' project."

3. Run a Database Query

Tool Name: create_a_supabase_database_query

Executes arbitrary SQL against a specific Supabase project or branch. Claude can use this to read application data, apply DDL migrations, or update records.

"Run a SQL query on the 'feature-add-users-table' branch to create a new table named 'profiles' with an id, email, and created_at timestamp."

4. Deploy an Edge Function

Tool Name: create_a_supabase_functions_deploy

Deploys or updates a Supabase Edge Function. Claude passes the metadata, entrypoint paths, and versioning info to spin up serverless logic.

"Deploy a new Edge Function called 'process-payments' to our staging project. Ensure JWT verification is enabled."

5. Update Auth Configuration

Tool Name: supabase_config_auths_bulk_update

Allows the LLM to modify the project's GoTrue auth settings. This includes toggling signups, updating SMTP mailer settings, or adjusting rate limits for authentication endpoints.

"Update the Auth configuration for the staging project. Disable public signups and set the site URL to our new staging domain."

6. List Database Migrations

Tool Name: list_all_supabase_database_migrations

Fetches the applied database migration history. Claude can use this to audit the state of a database schema before writing new SQL patches.

"List all applied database migrations for the production project. Tell me the name and version of the most recent migration."

To view the complete schema definitions and additional tools for managing storage, SSO, and more, check out the Supabase integration page.

Workflows in Action

Connecting Supabase to Claude via MCP turns conversational prompts into automated DevOps and database administration pipelines. Here is how Claude orchestrates multi-step workflows.

Workflow 1: Safe Database Schema Migration

In this scenario, a developer asks Claude to apply a schema change. Because the agent has access to branching tools, it can do this safely without touching the main production database directly.

"Find the 'e-commerce-prod' project. Create a new branch called 'add-inventory-column'. Once the branch is ready, run a SQL query to add an 'inventory_count' integer column to the 'products' table. Finally, fetch the schema diff."

Execution Steps:

1. list_all_supabase_projects: Claude searches the returned array for the project named "e-commerce-prod" and extracts its 20-character ref.
2. create_a_supabase_project_branch: Claude calls this tool with the extracted ref and branch_name: "add-inventory-column". It receives a branch_id in the response.
3. create_a_supabase_database_query: Claude executes the ALTER TABLE products ADD COLUMN inventory_count integer; query against the newly created branch.
4. list_all_supabase_branche_diffs: Claude requests the diff to verify the schema change was applied correctly.

sequenceDiagram
    participant Claude as Claude
    participant Truto as Truto MCP Server
    participant Supabase as Supabase API

    Claude->>Truto: Call list_all_supabase_projects
    Truto->>Supabase: GET /v1/projects
    Supabase-->>Truto: Project list
    Truto-->>Claude: Returns ref "a1b2c3d4e5f6g7h8i9j0"
    Claude->>Truto: Call create_a_supabase_project_branch
    Truto->>Supabase: POST /v1/projects/a1b2c3d4e5f6g7h8i9j0/branches
    Supabase-->>Truto: Branch created (branch_id)
    Truto-->>Claude: Returns branch_id
    Claude->>Truto: Call create_a_supabase_database_query
    Truto->>Supabase: POST /v1/projects/a1b2.../query (SQL payload)
    Supabase-->>Truto: Query success
    Truto-->>Claude: Returns execution result

Result: The developer gets confirmation that the branch is ready, the migration was applied to the isolated environment, and Claude outputs the exact schema diff for review.

Workflow 2: Edge Function Deployment and Auth Lockdown

An IT administrator needs to spin up a new internal tool environment, deploying serverless logic and locking down user access.

"Get the project reference for 'internal-admin-tools'. Deploy an Edge Function named 'slack-alert-webhook'. Then, update the Auth config for this project to completely disable new user signups."

Execution Steps:

1. list_all_supabase_projects: Claude finds "internal-admin-tools" and extracts the ref.
2. create_a_supabase_functions_deploy: Claude pushes the function metadata to the project using the extracted ref.
3. supabase_config_auths_bulk_update: Claude updates the GoTrue configuration, specifically setting disable_signup: true for that project.

sequenceDiagram
    participant Claude as Claude
    participant Truto as Truto MCP Server
    participant Supabase as Supabase API

    Claude->>Truto: Call list_all_supabase_projects
    Truto->>Supabase: GET /v1/projects
    Supabase-->>Truto: Project list
    Truto-->>Claude: Returns ref "z9y8x7w6v5u4t3s2r1q0"
    Claude->>Truto: Call create_a_supabase_functions_deploy
    Truto->>Supabase: POST /v1/projects/.../functions
    Supabase-->>Truto: Function deployed
    Truto-->>Claude: Returns deployment status
    Claude->>Truto: Call supabase_config_auths_bulk_update
    Truto->>Supabase: PATCH /v1/projects/.../config/auth
    Supabase-->>Truto: Auth config updated
    Truto-->>Claude: Returns new auth settings

Result: Claude provisions the Edge Function and secures the authentication perimeter in seconds, entirely through conversational commands.

Connect Supabase to Claude Today

Building a custom MCP server to handle Supabase's project references, authentication schemas, and branching logic takes weeks of engineering effort. Maintaining it as the API evolves takes even longer.

Truto abstracts that complexity away. By deriving MCP tools directly from the underlying API documentation, Truto gives your LLMs immediate, secure access to Supabase with built-in schema validation, standardized pagination, and pass-through rate limit handling.

Stop writing custom integration boilerplate.