O Claude Code é o agente de programação da Anthropic que roda no terminal. Ele lê o seu repositório, edita arquivos, roda comandos e testes, e repete até a tarefa ficar pronta. Sozinho, porém, ele só enxerga o que está na sua máquina. Para consultar o Sentry, abrir uma issue no Linear ou ler o que o cliente pediu no WhatsApp, ele precisa de servidores MCP.
Este guia mostra como adicionar, organizar e depurar servidores MCP no Claude Code, com os comandos da documentação oficial.
Em uma frase: o que o MCP faz no Claude Code
O MCP (Model Context Protocol) é o padrão que conecta o Claude Code a ferramentas externas. Cada servidor MCP entrega um conjunto de ferramentas, e o Claude decide quando usar cada uma durante a conversa. Se você ainda não conhece o protocolo, o texto o que é MCP explica do zero.
Adicionando um servidor remoto (HTTP)
Servidores que rodam na nuvem são adicionados pela URL:
claude mcp add --transport http notion https://mcp.notion.com/mcp
Se o serviço pede um token fixo, ele vai no cabeçalho:
claude mcp add --transport http minha-api https://api.exemplo.com/mcp \
--header "Authorization: Bearer SEU_TOKEN"
Muitos servidores remotos usam OAuth. Nesse caso, depois de adicionar, rode /mcp dentro da sessão para fazer o login no navegador.
Adicionando um servidor local (stdio)
Servidores locais rodam como um processo no seu computador. O formato é:
claude mcp add [opções] <nome> -- <comando> [argumentos...]
O -- separa as opções do Claude Code do comando que inicia o servidor. Tudo depois dele é repassado sem mudança. Variáveis de ambiente vão com --env (ou -e):
claude mcp add --env AIRTABLE_API_KEY=SUA_CHAVE --transport stdio airtable \
-- npx -y airtable-mcp-server
Um exemplo real com WhatsApp. O WACrew publica o servidor wacrew-mcp no npm, que liga o Claude Code ao painel do WhatsApp:
claude mcp add wacrew \
-e WAC_CLOUD_URL=https://seu-painel.exemplo.com \
-e WAC_CLOUD_USER=admin -e WAC_CLOUD_PASS=sua-senha \
-- npx -y wacrew-mcp
Depois disso, pedidos como "resume o que os clientes mandaram hoje" ou "transcreve o áudio do grupo X" passam a funcionar. O passo a passo completo está em como conectar o WhatsApp ao Claude Code com MCP.
Os três escopos: local, projeto e usuário
Onde a configuração fica guardada muda quem enxerga o servidor. Você escolhe com --scope (ou -s):
| Escopo | Vale em | Compartilhado com a equipe | Onde fica |
|---|---|---|---|
local (padrão) | Só no projeto atual | Não | ~/.claude.json |
project | Só no projeto atual | Sim, pelo Git | .mcp.json na raiz do projeto |
user | Todos os seus projetos | Não | ~/.claude.json |
Regras práticas:
- Credenciais pessoais ficam em
localouuser, nunca emproject. - Ferramentas que todo o time usa naquele repositório vão em
project. O arquivo.mcp.jsonentra no Git. - Ferramentas que você usa em tudo, como um servidor de busca, vão em
user.
O arquivo .mcp.json
No escopo de projeto, a configuração é um arquivo JSON na raiz do repositório:
{
"mcpServers": {
"wacrew": {
"command": "npx",
"args": ["-y", "wacrew-mcp"],
"env": {
"WAC_CLOUD_URL": "${WAC_CLOUD_URL}",
"WAC_CLOUD_USER": "${WAC_CLOUD_USER}",
"WAC_CLOUD_PASS": "${WAC_CLOUD_PASS}"
}
}
}
}
O ${VAR} é expandido a partir do seu ambiente, então a senha não precisa ficar no repositório. Por segurança, o Claude Code pede aprovação antes de ativar servidores vindos de um .mcp.json. Um repositório clonado não consegue se aprovar sozinho.
Gerenciando os servidores
claude mcp list # lista os servidores e o estado de cada um
claude mcp get wacrew # detalhes de um servidor
claude mcp remove wacrew # remove
Dentro de uma sessão, o comando /mcp mostra o estado das conexões, faz login em servidores com OAuth e liga ou desliga servidores no projeto sem apagar a configuração.
O claude mcp list mostra um estado ao lado de cada servidor, como "Connected", "Needs authentication" ou "Failed to connect". Uma falha ali quer dizer que o Claude Code não conseguiu conectar naquele servidor, não que o comando deu erro.
Problemas comuns e como resolver
O servidor aparece como "Pending approval". É um servidor de .mcp.json que você ainda não aprovou. Rode claude no projeto e aceite na caixa de confiança.
O servidor demora para subir. A variável MCP_TIMEOUT define o tempo de inicialização. Por exemplo, MCP_TIMEOUT=10000 claude dá dez segundos.
A ferramenta devolve texto demais. O Claude Code avisa quando a saída de uma ferramenta passa de 10 mil tokens e limita em 25 mil por padrão. A variável MAX_MCP_OUTPUT_TOKENS muda esse limite. Melhor ainda é a ferramenta aceitar filtros, como "últimas 50 mensagens", em vez de devolver tudo.
A variável de ambiente não chega. Lembre do -- no comando. Opções do Claude Code vão antes dele, e o comando do servidor vai depois. Coloque pelo menos uma opção entre --env e o nome do servidor, senão o nome é lido como mais uma variável.
Servidor do Claude Desktop ou do Cursor. Instruções escritas para outro cliente geralmente trazem um bloco JSON com command e args. Dá para usar o mesmo comando com claude mcp add ou colar o bloco com claude mcp add-json.
Boas práticas
- Poucos servidores por projeto. Cada servidor adiciona ferramentas que o modelo precisa considerar. Ferramentas demais confundem a escolha.
- Permissão mínima. Dê ao servidor a chave com menos poder que resolve o problema.
- Ações que saem para fora pedem confirmação. Envio de mensagem, publicação e pagamento devem passar pela sua aprovação. No caso do WhatsApp, o WACrew deixa cada conversa em modo confirmar por padrão.
- Teste antes de compartilhar. Valide em
locale só depois mova paraproject.
Resumo
O Claude Code ganha ferramentas externas com servidores MCP. Remotos entram com claude mcp add --transport http, locais com claude mcp add <nome> -- <comando>. O escopo decide se a configuração é só sua ou do time inteiro, e /mcp resolve o login e o diagnóstico.
Usa o Cursor também? O guia de Cursor com MCP mostra a configuração equivalente no editor.



