Pular para o conteúdo
🤖 MCP

MCP — IA fala com seu SuperDB.

Servidor MCP oficial. Claude, Cursor, Codex e Continue interagem direto com sua instância.

O servidor MCP liga o Claude Desktop, o Cursor ou o Codex ao banco do seu projeto. Eles passam a consultar o schema, rodar migrations, revisar as políticas de RLS e criar buckets — sem você sair do editor.

Conectar sem instalar nada (recomendado)

Desde agosto de 2026 existe um servidor MCP remoto. É a forma mais simples de conectar, e não usa este pacote:

https://mcp.superdb.com.br/mcp

Cole essa URL como conector no seu cliente MCP, faça login e escolha quais projetos aquele agente pode alcançar. Não há chave para copiar nem para guardar: a credencial nasce no consentimento e vive entre o cliente e o SuperDB.

  • Sem Node na sua máquina e sem pacote para atualizar.
  • Funciona no Claude web e no celular — um servidor local não alcança esses dois por construção.
  • Uma conexão, N projetos. Marcou três, alcança três; adicionar um quarto depois não exige reconectar. Ou marque todos, inclusive os novos: projeto que você criar entra sozinho.
  • Revogar corta na hora, em Conta → Aplicativos conectados. Quem sai de um projeto (ou deixa de ser admin) perde o acesso do agente a ele na chamada seguinte.
  • Você vê para onde o acesso vai. A tela de autorização mostra o endereço que recebe o acesso, ao lado do nome do aplicativo, e avisa quando ele não é um aplicativo conhecido: nesse caso, só autorize se foi você que iniciou a conexão.
  • Autorizar de novo substitui. Autorizar outra vez pelo mesmo aplicativo troca a conexão anterior dele pela nova, com os projetos marcados agora. Um aplicativo que só tem o mesmo nome não derruba a conexão de outro.

Escrevendo um cliente MCP próprio? O endereço de retorno do OAuth precisa ser https, ou http em localhost, 127.0.0.1 ou [::1] (qualquer porta), como pede a especificação de autorização do MCP. Outro esquema é recusado no registro e na autorização.

Detalhes e passo a passo: superdb.com.br/mcp.

💡

Quando usar o pacote local (o resto desta página)? Quando não houver navegador para completar o login — automação, CI, um script que roda sozinho. Aí a autenticação por management key é o caminho, e continua suportada.

O que você precisa

Duas coisas, as duas no painel em app.superdb.com.br:

  1. O ID do projeto — está na URL quando você abre o projeto.
  2. Uma management key — em Configurações › Chaves de gerenciamento. Ela aparece uma única vez; copie na hora.
⚠️

Use a management key, não a service role. A service role e a anon key não funcionam nestas rotas — e a service role é poderosa demais para ficar num arquivo de configuração do editor. A management key vale só para um projeto, é auditada por chave no servidor e você revoga quando quiser. Ela também vale só enquanto quem a criou for owner ou admin do projeto: se essa pessoa sair do time, ou virar member, as chaves que ela criou param na hora. Para CI e automação que ficam, crie a chave com a conta do dono.

Configuração por IDE

Claude Desktop

Arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows. Reinicie o app depois de salvar.

claude_desktop_config.json
{
  "mcpServers": {
    "superdb": {
      "command": "npx",
      "args": ["-y", "@superdb/mcp"],
      "env": {
        "SUPERDB_PROJECT_ID": "seu-uuid-de-projeto",
        "SUPERDB_MGMT_KEY": "sdb_pmk_..."
      }
    }
  }
}

Cursor

Arquivo: .cursor/mcp.json na raiz do projeto, com o mesmo bloco mcpServers acima.

Codex (OpenAI)

O Codex não lê o JSON acima: a configuração dele é em TOML, em ~/.codex/config.toml (vale para a CLI, a extensão da IDE e o app). O jeito mais simples é o servidor remoto, com login pelo navegador:

~/.codex/config.toml
[mcp_servers.superdb]
url = "https://mcp.superdb.com.br/mcp"

Depois rode codex mcp login superdb e escolha os projetos. Para automação, sem navegador, use a management key numa variável de ambiente:

~/.codex/config.toml — com management key
[mcp_servers.superdb]
url = "https://mcp.superdb.com.br/mcp"
bearer_token_env_var = "SUPERDB_MGMT_KEY"
env_http_headers = { "X-SuperDB-Project-Id" = "SUPERDB_PROJECT_ID" }

O caminho por login (codex mcp login superdb) foi testado por nós em setembro de 2026. O bloco com management key segue a documentação do Codex. Se algo não conectar, escreva para contato@superdb.com.br.

Ferramentas disponíveis

  • superdb_query_sql — consulta com SQL sem alterar nada: a transação roda em modo somente leitura, e o Postgres recusa INSERT, UPDATE, DELETE e DDL. Marcada como só leitura, o cliente pode rodá-la sem pedir confirmação.
  • superdb_run_sql — roda SQL que altera o projeto. Aceita SELECT e DDL (CREATE TABLE, ALTER, CREATE POLICY): é o mesmo executor das migrations.
  • superdb_list_tables — lista as tabelas, separando as suas das auth_* que o SuperDB mantém.
  • superdb_describe_table — colunas de uma tabela: tipo, se aceita nulo, valor padrão e chave primária.
  • superdb_list_policies — políticas de RLS. Sem argumento, mostra as do projeto inteiro — serve para achar tabela desprotegida.
  • superdb_list_buckets — buckets de Storage.
  • superdb_create_bucket — cria bucket. Privado por padrão.

Ferramentas do SuperDB Fiscal

Para quem ativou o SuperDB Fiscal no projeto (planos Pro e Escala). Usam a mesma chave de gestão, e tanto o MCP remoto quanto o pacote @superdb/mcp (a partir da 0.4.0) já as trazem.

  • fiscal_listar_notas: lista as NFS-e do projeto, da mais nova para a mais antiga. Só leitura.
  • fiscal_consultar_nota: uma nota pelo id: situação, número, chave de acesso, ambiente e, se foi recusada, o código, o motivo e a dica. Só leitura.
  • fiscal_previa_nfse: confere o pedido e devolve o XML da DPS e o tamanho do PDF de exemplo. Sem valor fiscal, sem gravar e sem gastar a cota do mês.
  • fiscal_prontidao: o que falta para o emitente emitir e o estado do pedido de produção. Só leitura.
  • fiscal_emitir_nfse: pede a emissão, de forma idempotente pela ref. Sai no ambiente do emitente: em homologação não tem valor fiscal; em produção a nota tem valor fiscal e só sai com confirmar_producao: true, depois de a pessoa confirmar.
  • fiscal_cancelar_nfse: cancela uma nota já emitida. Não se desfaz.

Quem coloca o emitente em produção é o dono do projeto, pelo painel, e a equipe do SuperDB confere e libera. Para desligar as ferramentas fiscais no servidor local, defina SUPERDB_FISCAL_TOOLS=0.

Variáveis de ambiente

  • SUPERDB_PROJECT_ID — obrigatória. UUID do projeto.
  • SUPERDB_MGMT_KEY — obrigatória. A chave sdb_pmk_….
  • SUPERDB_URL — opcional (default https://auth.superdb.com.br).

Exemplos de prompt

  • "Quais tabelas minhas ainda não têm política de RLS?"
  • "Cria uma tabela de agendamentos com FK para pacientes, e a policy que isola por clínica."
  • "Descreve a tabela de pacientes e me diz quais colunas guardam dado pessoal."
  • "Roda essa migration e confirma que a coluna entrou."

Limites

  • SELECT sem LIMIT recebe LIMIT 1000 automaticamente.
  • Cada query tem timeout de 30 segundos.
  • As chamadas são rate-limited e auditadas por chave, no servidor.
  • O executor recusa schemas de sistema (information_schema, pg_catalog, storage, auth_global). Se você escrever a query à mão, use pg_tables e pg_policies sem qualificar o schema.
Essa página ajudou?