Supabase MCP Server

To connect AI assistants like Cursor, Claude, or Windsurf to your Supabase projects, configure your MCP client using the HTTP transport. Most clients require a JSON configuration. You can also generate a custom MCP URL via the MCP connection tab in your Supabase dashboard.

Cloud (Production): Use https://mcp.supabase.com/mcp.

Local Development (Supabase CLI): If running Supabase locally, use http://localhost:54321/mcp. Note that the CLI version offers a limited subset of tools and does not support OAuth 2.1.

Self-hosted: For Docker-based self-hosted environments, check the Supabase documentation for enabling the MCP server. These environments also offer a limited subset of tools and no OAuth 2.1.

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

The Supabase MCP server supports a branching workflow to safely experiment with schema changes. You can use a development branch to clone your production branch by applying the same migrations.

Core Workflow Tools:

• create_branch: Creates a development branch by cloning the production branch using migrations from list_migrations.
• merge_branch: Merges a development branch into production by applying new migrations incrementally. If a merge fails, the status becomes MIGRATIONS_FAILED; use get_logs to diagnose.
• rebase_branch: Synchronizes a development branch with production when production is ahead (e.g., after a hotfix or when multiple developers merge branches in different orders).
• delete_branch: Deletes a development branch to save on resource costs ($0.01344 per hour per active branch).
• reset_branch: An escape hatch to reset the development branch. It can reset to the latest migration (dropping untracked data) or to a specific migration version.

The StreamTransport utility allows you to connect an MCP client and an MCP server directly in-memory or over a custom stream-based transport. It implements a duplex stream interface using standard Web ReadableStream and WritableStream objects.

To connect a client and server in-memory, create two StreamTransport instances and use pipeTo to connect the client's readable stream to the server's writable stream, and vice versa.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamTransport } from '@supabase/mcp-utils';
import { PostgrestMcpServer } from '@supabase/mcp-server-postgrest';

// Create a stream transport for both client and server
const clientTransport = new StreamTransport();
const serverTransport = new StreamTransport();

// Connect the streams together
clientTransport.readable.pipeTo(serverTransport.writable);
serverTransport.readable.pipeTo(clientTransport.writable);

const client = new Client(
  {
    name: 'MyClient',
    version: '0.1.0',
  },
  {
    capabilities: {},
  }
);

const server = new PostgrestMcpServer({
  apiUrl: API_URL,
  schema: 'public',
});

// Connect the client and server to their respective transports
await server.connect(serverTransport);
await client.connect(clientTransport);

If building a custom MCP client, you can use createPostgrestMcpServer from @supabase/mcp-server-postgrest. For in-memory connections or custom piping, use StreamTransport from @supabase/mcp-utils to connect the client and server transports.

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamTransport } from '@supabase/mcp-utils';
import { createPostgrestMcpServer } from '@supabase/mcp-server-postgrest';

// Create a stream transport for both client and server
const clientTransport = new StreamTransport();
const serverTransport = new StreamTransport();

// Connect the streams together
clientTransport.readable.pipeTo(serverTransport.writable);
serverTransport.readable.pipeTo(clientTransport.writable);

const client = new Client(
  {
    name: 'MyClient',
    version: '0.1.0',
  },
  {
    capabilities: {},
  }
);

const supabaseUrl = 'https://your-project-ref.supabase.co'; // http://127.0.0.1:54321 for local
const apiKey = 'your-anon-key'; // or service role, or user JWT
const schema = 'public'; // or any other exposed schema

const server = createPostgrestMcpServer({
  apiUrl: `${supabaseUrl}/rest/v1`,
  apiKey,
  schema,
});

// Connect the client and server to their respective transports
await server.connect(serverTransport);
await client.connect(clientTransport);

// Call tools, etc
const output = await client.callTool({
  name: 'postgrestRequest',
  arguments: {
    method: 'GET',
    path: '/todos',
  },
});

The @supabase/mcp-server-supabase package provides createToolSchemas() to enable static tool usage with the Vercel AI SDK's MCP client. This provides client-side validation and inferred TypeScript types for tool inputs and outputs.

To use it, initialize an MCPClient with the Supabase HTTP transport and pass the result of createToolSchemas() to the .tools() method.

import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas(),
});

const result = streamText({ model, tools, prompt: '...' });

for (const step of await result.steps) {
  for (const toolResult of step.staticToolResults) {
    if (toolResult.toolName === 'get_project_url') {
      toolResult.input;  // { project_id: string }
      toolResult.output; // { url: string }
    }
  }
}