MCP no Claude Code: como conectar bancos de dados e APIs

Índice

• Referência rápida
• Como funciona o MCP
• Passo 1: adicionar um servidor local (stdio)
• Passo 2: conectar um servidor remoto (HTTP)
• Passo 3: escolher o scope
• Passo 4: compartilhar a configuração sem compartilhar segredos
• Passo 5: verificar se funciona
• 8 regras de segurança antes de conectar algo sério
• E o Superpowers, onde entra?
• Plano para a sua equipe

Assim que instalado, o Claude Code lê arquivos e executa comandos no seu terminal. Para que ele consulte seu banco de dados, revise suas issues ou chame uma API, você precisa do MCP (Model Context Protocol), o protocolo aberto que a Anthropic publicou para conectar modelos a ferramentas externas.

Este guia explica como adicionar servidores MCP, como compartilhá-los com a equipe sem subir credenciais para o Git e quais regras de segurança seguir antes de conectar algo sério.

Referência rápida

Servidor	Transporte	Comando	Scope sugerido	Cuidado principal
Git local	stdio (uvx)	claude mcp add git -- uvx mcp-server-git	user	Verifique quais operações de escrita ele expõe
PostgreSQL	stdio (npx)	claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"	project	Somente com um usuário de leitura
API remota	http	claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp	project	O token vai em uma variável, nunca no arquivo
Sistema de arquivos	stdio (npx)	claude mcp add archivos -- npx -y @modelcontextprotocol/server-filesystem .	local	Limite o caminho ao projeto, nunca à raiz do disco

Como funciona o MCP

O Claude Code atua como cliente. Cada servidor MCP é um processo ou serviço que expõe ferramentas, por exemplo run_query ou list_issues. Durante a sessão, o Claude vê essas ferramentas, decide quando chamá-las e pede sua permissão de acordo com a sua configuração.

Há duas formas de se conectar:

• stdio: o Claude Code inicia o servidor como um processo local (normalmente com npx ou uvx) e se comunica pela entrada e saída padrão. É o habitual para ferramentas que rodam na sua máquina.
• http: o servidor fica em uma URL remota. É o habitual para serviços na nuvem. Muitos dos grandes serviços publicam servidores MCP oficiais com autenticação OAuth.

Passo 1: adicionar um servidor local (stdio)

A forma geral é:

claude mcp add <nombre> -- <comando> [argumentos...]

O separador -- é obrigatório: ele separa as opções do claude do comando que inicia o servidor. Sem ele, o Claude Code tenta interpretar os argumentos do servidor como se fossem dele.

Exemplo com um servidor de Git:

claude mcp add git -- uvx mcp-server-git

Exemplo com PostgreSQL usando DBHub, apontando para uma variável de ambiente com um usuário somente leitura:

export DATABASE_READONLY_URL="postgresql://lectura:****@db.tuempresa.com:5432/analytics"
claude mcp add db -- npx -y @bytebase/dbhub --dsn "$DATABASE_READONLY_URL"

Passo 2: conectar um servidor remoto (HTTP)

claude mcp add --transport http mi-api https://mcp.ejemplo.com/mcp \
  --header "Authorization: Bearer $MI_API_TOKEN"

Se o servidor usar OAuth, não coloque o header: entre na sessão, execute /mcp e siga o fluxo de autenticação no navegador.

Passo 3: escolher o scope

Cada servidor é salvo em um dos três escopos, que você escolhe com --scope:

• local (padrão): só para você e só neste projeto. Útil para testes ou servidores com credenciais pessoais.
• project: gravado em .mcp.json, na raiz do repositório. Toda a equipe o recebe ao clonar. O Claude Code pede aprovação na primeira vez que alguém usa um servidor do projeto.
• user: para você em todos os seus projetos. Ideal para ferramentas gerais como o Git.

claude mcp add --scope project db -- npx -y @bytebase/dbhub --dsn '${DATABASE_READONLY_URL}'

Passo 4: compartilhar a configuração sem compartilhar segredos

O arquivo .mcp.json aceita variáveis de ambiente com a sintaxe ${VARIABLE} (e ${VARIABLE:-valor_padrao}). Assim o arquivo pode ir para o repositório sem credenciais:

{
  "mcpServers": {
    "mi-api": {
      "type": "http",
      "url": "https://mcp.ejemplo.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MI_API_TOKEN}"
      }
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_READONLY_URL}"]
    }
  }
}

Cada desenvolvedor exporta as próprias variáveis (export MI_API_TOKEN=...) ou as carrega de um gerenciador de segredos, e ninguém precisa mexer no arquivo.

Passo 5: verificar se funciona

claude mcp list        # estado de todos los servidores
claude mcp get db      # detalle de uno
claude mcp remove db   # eliminarlo

Dentro de uma sessão, /mcp mostra quais servidores estão conectados e quais ferramentas expõem. Se um servidor aparecer com erro, a causa mais comum é uma variável de ambiente não definida no shell em que você abriu o Claude Code.

8 regras de segurança antes de conectar algo sério

1. Mínimo privilégio. Usuários de banco somente leitura, tokens com as permissões estritamente necessárias. Nunca dê ao agente um usuário administrador.
2. Zero segredos no repositório. Variáveis de ambiente no .mcp.json, sempre.
3. Caminhos restritos. O servidor de arquivos só deve enxergar a pasta do projeto.
4. Servidores oficiais ou revisados. Prefira os publicados pelo próprio fornecedor do serviço. Um servidor MCP executa código na sua máquina: verifique de onde ele vem antes de instalar.
5. Aprovação humana para o que escreve. Use as permissões do Claude Code para que as ferramentas que modificam dados peçam confirmação, ou um hook PreToolUse com um matcher como mcp__db__.* para bloquear ou registrar certas chamadas.
6. Timeouts razoáveis. Se um servidor demora para iniciar (o primeiro download com npx costuma ser lento), aumente o tempo de espera com a variável MCP_TIMEOUT, em milissegundos.
7. Limite de saída. Se uma ferramenta devolver resultados enormes, ajuste MAX_MCP_OUTPUT_TOKENS e peça consultas com LIMIT para não lotar o contexto do modelo.
8. Réplicas antes da produção. Para análises, conecte uma réplica ou um ambiente de staging, não a base principal.

E o Superpowers, onde entra?

O MCP dá ao Claude Code acesso a ferramentas. O Superpowers lhe dá um método: um plugin de skills que o obriga a desenhar antes de programar, escrever um plano por etapas e trabalhar com testes primeiro. Eles são complementares: com o MCP, o Claude pode consultar seu banco de dados; com o Superpowers, ele faz isso dentro de um plano revisado.

Se você ainda não o tem, o guia de como instalar o Superpowers no Claude Code explica a instalação pelo marketplace em cinco minutos.

Plano para a sua equipe

1. Padronize a ferramenta. Instale o Claude Code na equipe e decida quais servidores são de uso geral (scope user) e quais são do projeto.
2. Crie credenciais para a IA. Peça à infraestrutura um usuário de banco de dados dedicado, somente leitura e com acesso limitado aos esquemas necessários.
3. Versione o .mcp.json. Suba-o para o repositório com variáveis de ambiente e documente no README quais variáveis cada desenvolvedor precisa.
4. Meça o impacto. Se a equipe resolve mais rápido, isso muda a sua estrutura de custos. Faça as contas com a calculadora de margem de lucro.