WACrew

Blog

Claude Code e MCP: o que é e como ligar ferramentas externas

O que é o Claude Code e como conectar ferramentas externas com MCP. Comandos claude mcp add, escopos local, projeto e usuário, .mcp.json e solução de problemas.

Por Rodrigo Sumioshi 5 min de leitura
Neste artigo
  1. Em uma frase: o que o MCP faz no Claude Code
  2. Adicionando um servidor remoto (HTTP)
  3. Adicionando um servidor local (stdio)
  4. Os três escopos: local, projeto e usuário
  5. O arquivo .mcp.json
  6. Gerenciando os servidores
  7. Problemas comuns e como resolver
  8. Boas práticas
  9. Resumo

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):

EscopoVale emCompartilhado com a equipeOnde fica
local (padrão)Só no projeto atualNão~/.claude.json
projectSó no projeto atualSim, pelo Git.mcp.json na raiz do projeto
userTodos os seus projetosNão~/.claude.json

Regras práticas:

  • Credenciais pessoais ficam em local ou user, nunca em project.
  • Ferramentas que todo o time usa naquele repositório vão em project. O arquivo .mcp.json entra 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

  1. Poucos servidores por projeto. Cada servidor adiciona ferramentas que o modelo precisa considerar. Ferramentas demais confundem a escolha.
  2. Permissão mínima. Dê ao servidor a chave com menos poder que resolve o problema.
  3. 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.
  4. Teste antes de compartilhar. Valide em local e só depois mova para project.

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.