MCP — Model Context Protocol

Overview

Supabyoi exposes the Supabase MCP (Model Context Protocol) server through the instance's Kong API gateway. Once enabled, AI tools can query your database, inspect schema, run SQL, and manage your Supabase project without leaving your editor — all protected by the same gateway key-auth that secures every other API endpoint.

The MCP server is built into Supabase Studio and speaks the Streamable HTTP transport — a POST endpoint that can respond with either JSON or a Server-Sent Events stream. Both formats are supported by all major MCP clients.

Security Warning

Enabling MCP

MCP is disabled by default. Enable it from the instance Settings page:

1. 1 Open the instance detail page and click Settings.
2. 2 Under Advanced Configuration, toggle Enable MCP Server on.
3. 3 Supabyoi reconfigures the Kong gateway and restarts the router. The process takes roughly 10–15 seconds. Once complete, the /mcp route becomes active on your instance URL.

To disable MCP, toggle the setting off. Kong will be reconfigured to drop all /mcp requests.

Endpoint & Authentication

Endpoint URL

The MCP endpoint is always at the root of your instance URL:

Replace <subdomain> with your instance subdomain, shown on the instance detail page.

Authentication

Every request must include an apikey header set to your instance's Secret Key (the sb_secret_… token). This is the service_role key — the same one shown in the Credentials panel on your instance page.

Do not use the Authorization: Bearer … header — Kong's key-auth plugin reads apikey, not Authorization, on the MCP route.

Connecting Claude Code

Add the server to your project's .mcp.json file (or to ~/.claude/mcp.json for a user-level config that applies to all projects):

{
  "mcpServers": {
    "supabyoi": {
      "type": "http",
      "url": "https://<subdomain>.supabyoi.com/mcp",
      "headers": {
        "apikey": "sb_secret_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

After saving, restart Claude Code (or run /mcp in a session to reload MCP servers). The Supabase tools — SQL runner, table browser, schema inspector — will be available to the assistant.

Connecting Cursor

Open Cursor's MCP settings (Cursor → Settings → MCP) and add a new server entry, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "supabyoi": {
      "url": "https://<subdomain>.supabyoi.com/mcp",
      "headers": {
        "apikey": "sb_secret_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor's MCP client uses the Streamable HTTP transport automatically when a url is provided without a command field.

Other MCP Clients

Any MCP client that supports the Streamable HTTP transport can connect. The canonical configuration is:

• URL: https://<subdomain>.supabyoi.com/mcp
• Method: POST
• Header: apikey: <service_role_key>
• Content-Type: application/json

The gateway sets response_buffering: false so SSE streams are forwarded in real time. Clients that request Accept: text/event-stream will receive a streaming response; others receive a single JSON envelope.

Verifying the Connection

Send an initialize request to confirm the endpoint is reachable and the key is accepted:

curl -X POST \
  https://<subdomain>.supabyoi.com/mcp \
  -H "Content-Type: application/json" \
  -H "apikey: sb_secret_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

A successful response looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "Supabase MCP Server", "version": "0.7.0" },
    "capabilities": { ... }
  }
}

Common errors:

• 401 Unauthorized — wrong or missing apikey header. Check that you are using the service_role (secret) key, not the anon (publishable) key.
• 404 Not Found — MCP is not enabled on this instance. Toggle it on in Settings first.
• 403 Forbidden — the key is valid but not in the admin ACL group. This should not happen with the service_role key; if it does, contact support.

How It Works

Supabase Studio (running on each instance at port 3000) includes a built-in MCP server at /api/mcp. When you enable MCP in Settings, Supabyoi:

1. 1 Regenerates the Kong declarative config to add an /mcp service route pointing at studio:3000/api/mcp.
2. 2 Attaches key-auth (requires apikey header) and ACL (allow: admin group only) plugins to the route, so only the service_role key can reach it.
3. 3 Restarts the Kong container so it picks up the updated config, then health-checks the instance. If anything fails, the old config is automatically restored.

The route is configured with response_buffering: false so that SSE streams are forwarded immediately through Kong without buffering. No SSH tunnel or IP-level restriction is required — authentication is handled entirely at the Kong gateway layer.