Servidor MCP (Claude, Cursor)

O DIVZ publica um servidor MCP oficial que dá a um agente de IA acesso direto aos seus bancos: listar projetos, rodar SQL, criar branches e ver estatísticas. Instala com npx e autentica com a mesma chave da API.

O que o MCP resolve

MCP (Model Context Protocol) é o padrão aberto que permite a um assistente de IA usar ferramentas externas. Com o servidor MCP do DIVZ configurado, você conversa com o banco em vez de alternar entre editor, terminal e console:

“Quais tabelas existem no projeto loja e quantas linhas cada uma tem?”
“Cria um branch a partir da main para eu testar essa migração.”
“Qual o cache hit ratio do banco de produção agora?”
“Quem mexeu nesse projeto nos últimos dias?”

O agente conversa com a API do DIVZ usando a sua chave, respeitando o escopo dela. Ele não recebe acesso privilegiado nem enxerga projeto de outra conta.

Instalar

O servidor roda por stdio e precisa de Node 20 ou superior. Clone o repositório e compile:

terminal

git clone https://github.com/agenciaraca/divz.git
cd divz/packages/mcp
npm install
npx tsc          # gera dist/index.js

Claude Desktop

Edite claude_desktop_config.json (menu Configurações → Desenvolvedor → Editar configuração) e acrescente:

claude_desktop_config.json

{
  "mcpServers": {
    "divz": {
      "command": "node",
      "args": ["/caminho/para/divz/packages/mcp/dist/index.js"],
      "env": {
        "DIVZ_API_KEY": "divz_sua_chave_aqui"
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas do DIVZ aparecem na lista de ferramentas.

Cursor, Claude Code e outros clientes

Qualquer cliente compatível com MCP por stdio funciona com a mesma configuração: comando node, o caminho do dist/index.js e a variável DIVZ_API_KEY. Para apontar a outro ambiente, defina também DIVZ_API_URL (o padrão é https://api.divz.com.br).

As 16 ferramentas

Ferramenta	O que faz	Escopo mínimo
list_projects	lista os projetos com status, região e branches	READ
list_tables	tabelas do schema public	READ
run_sql	executa SQL e devolve as linhas	READ (só leitura) · READ_WRITE (escrita)
project_stats	tamanho, nº de tabelas, conexões, cache hit ratio, maiores tabelas	READ
project_activity	trilha de auditoria do projeto	READ
list_branches	branches com LSN e tamanho no storage engine	READ
list_extensions	extensões instaladas e disponíveis	READ
list_roles	roles com as connection strings (devolve segredos)	READ_WRITE — em READ a string vem oculta
get_ip_allow	allowlist de IPs do projeto	READ
create_project	cria um projeto novo	READ_WRITE
create_branch	cria um branch copy-on-write	READ_WRITE
install_extension	instala extensão da allowlist	READ_WRITE
create_app_role	cria o role de aplicação (respeita RLS)	READ_WRITE
rotate_app_role	rotação suave da senha do role de app	READ_WRITE
rotate_credentials	rotaciona a senha do dono (quebra strings antigas)	READ_WRITE
set_ip_allow	substitui a allowlist de IPs	READ_WRITE

O que ele deliberadamente não faz

Não há ferramenta para apagar projeto, apagar branch ou restaurar PITR. Isso é escolha de projeto, não esquecimento: são operações irreversíveis, e ficariam a um mal-entendido de linguagem natural de distância. Para elas, o console pede confirmação explícita de um humano.

Se você quer um agente que só observa, gere uma chave de escopo READ. Ela roda SELECT normalmente, mas qualquer escrita é recusada pelo próprio PostgreSQL — a consulta executa dentro de uma transação READ ONLY, então UPDATE, DELETE, CREATE, SELECT INTO e até CTE com escrita falham no banco, não numa checagem de texto que poderia ser contornada.

Duas consequências práticas do escopo READ, ambas propositais: um comando por consulta (mandar select 1; select 2 devolve cannot insert multiple commands into a prepared statement — é o que impede o ponto e vírgula de virar rota de fuga da transação read-only), e nenhuma credencial nas respostas: list_roles e a listagem de projetos devolvem a connection string oculta. Para receber credencial, use READ_WRITE.

list_roles devolve connection strings com senha. Num assistente, isso significa credencial no histórico da conversa. Use quando precisar, sabendo disso — e rotacione a senha se a conversa for compartilhada.

Conferir se está funcionando

Se o cliente não listar as ferramentas, rode o servidor direto no terminal: ele escreve o motivo do erro na saída de erro padrão.

terminal

DIVZ_API_KEY=divz_... node dist/index.js
# esperado: DIVZ MCP server pronto (stdio).
# sem a variável: ERRO: defina DIVZ_API_KEY (gere em console.divz.com.br → …)

O servidor fica esperando mensagens na entrada padrão — não sair de volta ao prompt é o comportamento correto. Encerre com Ctrl+C.

Próximo: Migrar um banco existente