Supabase MCP

Servidor Supabase MCP

Conecte seus projetos Supabase ao Cursor, Claude, Windsurf e outros assistentes de IA.

O Model Context Protocol (MCP) padroniza como Modelos de Linguagem de Grande Escala (LLMs) se comunicam com serviços externos como o Supabase. Ele conecta assistentes de IA diretamente ao seu projeto Supabase e permite que eles executem tarefas como gerenciar tabelas, buscar configurações e consultar dados. Veja a lista completa de ferramentas.

Configuração

1. Siga nossas práticas recomendadas de segurança

Antes de configurar o servidor MCP, recomendamos que você leia nossas práticas recomendadas de segurança para entender os riscos de conectar um LLM aos seus projetos Supabase e como mitigá-los.

2. Configure seu cliente MCP

Para configurar o servidor Supabase MCP no seu cliente, visite nossa documentação de configuração. Você também pode gerar uma URL MCP personalizada para o seu projeto visitando a aba de conexão MCP no painel do Supabase.

Seu cliente MCP solicitará automaticamente que você faça login no Supabase durante a configuração. Certifique-se de escolher a organização que contém o projeto com o qual deseja trabalhar.

A maioria dos clientes MCP exige as seguintes informações:

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

Se você não encontrar seu cliente MCP listado em nossa documentação, verifique a documentação MCP do seu cliente e copie as informações MCP acima no formato esperado (json, yaml, etc).

CLI

Se você estiver executando o Supabase localmente com o Supabase CLI, poderá acessar o servidor MCP em http://localhost:54321/mcp. Atualmente, o Servidor MCP em ambientes CLI oferece um subconjunto limitado de ferramentas e não possui OAuth 2.1.

Self-hosted

Para Supabase self-hosted, consulte a página Habilitando o servidor MCP. Atualmente, o Servidor MCP em ambientes self-hosted oferece um subconjunto limitado de ferramentas e não possui OAuth 2.1.

Opções de configuração e ferramentas

Consulte a documentação do Servidor Supabase MCP para obter a lista completa de ferramentas disponíveis e opções de configuração.

A documentação também apresenta um construtor de URL interativo para preencher as opções de configuração para você.

Uso com o Cliente MCP do AI SDK

O pacote @supabase/mcp-server-supabase exporta createToolSchemas() para preencher esquemas de entrada e saída para o cliente MCP do Vercel AI SDK. Isso permite que as ferramentas Supabase MCP sejam tratadas como ferramentas estáticas com validação no lado do cliente e tipos TypeScript inferidos para suas entradas e saídas.

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 }
    }
  }
}

createToolSchemas() aceita opções de filtragem semelhantes aos parâmetros de URL do servidor MCP:

• features: Restringir a grupos de recursos específicos (por exemplo, ['database', 'docs']). O padrão são todos os grupos de recursos padrão.
• projectScoped: Quando true, omite project_id dos esquemas de entrada das ferramentas e exclui ferramentas de nível de conta — use ao conectar a um servidor configurado com project_ref. O padrão é false.
• readOnly: Quando true, exclui ferramentas de mutação — use ao conectar a um servidor configurado com read_only=true. O padrão é false.

const mcpClient = await createMCPClient({
  transport: {
    type: 'http',
    url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
  },
});

const tools = await mcpClient.tools({
  schemas: createToolSchemas({
    features: ['database', 'docs'],
    projectScoped: true,
    readOnly: true,
  }),
});

[!NOTE] Este servidor não envia structuredContent nos resultados das ferramentas MCP. O AI SDK recorre à análise de JSON a partir do texto content.

Para mais informações, consulte Definição de Esquema e Saídas de Ferramentas Tipadas na documentação do AI SDK.

Self-hosting do endpoint MCP

O pacote @supabase/mcp-server-supabase exporta createSupabaseMcpHandler() para servir as ferramentas via HTTP a partir do seu próprio endpoint. Ele aceita o mesmo SupabaseMcpServerOptions que createSupabaseMcpServer(), principalmente platform.

O handler fala apenas a revisão atual do protocolo. Ele é criado com legacy: 'reject', portanto, um cliente que fala apenas o protocolo da era 2025 recebe um HTTP 400 em vez de ser atendido.

Quando platform carrega uma credencial por solicitação, crie o handler por solicitação e feche-o quando a resposta terminar. O handler encapsula o platform que você fornece, portanto, um compartilhado atende a cada solicitação com essa plataforma.

Um handler de longa duração é adequado quando o platform deve ser compartilhado, por exemplo, um token de conta de serviço. Crie-o uma vez e close() no encerramento em vez de por resposta, pois close() derruba o roteador de assinaturas e recusa solicitações posteriores.

import { createServer } from 'node:http';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase';
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api';

const server = createServer((req, res) => {
  const accessToken = getAccessTokenFromRequest(req); // your own auth

  const handler = createSupabaseMcpHandler({
    platform: createSupabaseApiPlatform({ accessToken }),
  });

  // `close()` aborts in-flight exchanges, so close on `res` finishing rather
  // than when the handler resolves, which would cut streaming responses short.
  res.on('close', () => {
    handler.close().catch((error) => console.error(error));
  });

  toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});

toNodeHandler vem de @modelcontextprotocol/node, que não é uma dependência deste pacote. Instale-o junto.

Outros servidores MCP

@supabase/mcp-server-postgrest

O servidor MCP PostgREST permite que você conecte seus próprios usuários ao seu aplicativo via API REST. Veja mais detalhes no README do projeto.

Recursos

• Model Context Protocol: Saiba mais sobre o MCP e suas capacidades.
• Do desenvolvimento à produção: Aprenda como promover alterações com segurança para ambientes de produção.

Para desenvolvedores

Consulte CONTRIBUTING para obter detalhes sobre como contribuir com este projeto.

Licença

Este projeto é licenciado sob Apache 2.0. Consulte o arquivo LICENSE para obter detalhes.