@superdb/mcp

Servidor MCP (Model Context Protocol) do SuperDB. Liga o Claude Desktop, o Cursor ou o Codex ao banco do seu projeto: eles consultam o schema, rodam migrations, revisam as políticas de RLS e criam buckets de Storage — sem você sair do editor.

Antes de tudo: você provavelmente quer o servidor REMOTO

Desde agosto de 2026 existe uma forma melhor de conectar, que 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 os projetos. Sem Node na máquina, sem chave para guardar, sem versão para atualizar — e funciona no Claude web e no celular, que um servidor local não alcança por construção. Uma conexão vale para quantos projetos você autorizar.

👉 superdb.com.br/mcp

Então quando usar ESTE pacote?

Quando não houver navegador para completar o login: automação, CI, um script que roda sozinho. Aí a autenticação por management key deste pacote é o caminho — e continua suportada.

Instalação

Não precisa instalar: os editores abaixo já chamam via npx.

Configuração

Você precisa de 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, clique em criar. Ela aparece uma única vez; copie na hora.

A management key vale só para esse projeto e você pode revogá-la a qualquer momento. Não use aqui a service role nem a anon key — elas não funcionam nestas rotas, e a service role é poderosa demais para ficar num arquivo de configuração do editor.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Reinicie o Claude Desktop depois de salvar.

Cursor

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

Ferramentas

| Ferramenta | O que faz | |---|---| | superdb_query_sql | Consulta com SQL sem alterar nada: a transação roda somente leitura, e o Postgres recusa INSERT/UPDATE/DELETE/DDL. | | 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, nulo, 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. |

Com um group configurado (SUPERDB_GROUP_ID + SUPERDB_GROUP_KEY), aparecem também as três da SaaS factory:

| Ferramenta | O que faz | |---|---| | superdb_group_status | Estado do group: template em vigor, de onde sai a próxima versão, e quantos clientes ficaram na versão anterior. Chame antes de publicar. | | superdb_publish_template | Congela o schema atual como versão nova do molde. Passo de deploy, depois das migrations. Não retroage. | | superdb_list_tenants | Lista os clientes provisionados no group. |

SuperDB Fiscal

As ferramentas de nota fiscal vêm ligadas e usam a mesma chave de gestão. O projeto precisa do SuperDB Fiscal ativo (planos Pro e Escala; a ativação é no painel, em Notas fiscais). Para desligá-las no servidor local, defina SUPERDB_FISCAL_TOOLS=0.

| Ferramenta | O que faz | |---|---| | 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, recusa e dica. Só leitura. | | fiscal_previa_nfse | Confere o pedido e devolve o XML da DPS e o tamanho do PDF de exemplo (o PDF se vê no painel). Sem valor fiscal, sem gravar. | | fiscal_prontidao | O que falta para o emitente emitir. Só leitura. | | fiscal_emitir_nfse | Pede a emissão. Idempotente pela ref. Em produção só com confirmar_producao: true. | | fiscal_cancelar_nfse | Cancela uma nota emitida. Não se desfaz. |

A emissão sai no ambiente do emitente: em homologação não tem valor fiscal, e o assistente pode testar à vontade. Pedir a produção é do dono do projeto, pelo painel, e a equipe libera.

O que dá para pedir

"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."

Variáveis de ambiente

| Variável | Obrigatória | Padrão | |---|---|---| | SUPERDB_PROJECT_ID | sim | — | | SUPERDB_MGMT_KEY | sim | — | | SUPERDB_URL | não | https://auth.superdb.com.br |

Limites

• SELECT sem LIMIT recebe LIMIT 1000 automaticamente.
• Cada query tem timeout de 30s.
• As chamadas são rate-limited e auditadas por chave, no servidor.
• O executor recusa acesso a schemas de sistema (information_schema, pg_catalog, storage, auth_global). As ferramentas de introspecção já contornam isso — se você escrever a query à mão, use pg_tables e pg_policies sem qualificar o schema.

Licença

MIT — veja LICENSE.