# 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, 14 de novembro de 2026. Original: https://wacrew.com.br/blog/claude-code-mcp/

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](https://code.claude.com/docs/en/mcp).

## 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](https://wacrew.com.br/blog/o-que-e-mcp/) explica do zero.

## Adicionando um servidor remoto (HTTP)

Servidores que rodam na nuvem são adicionados pela URL:

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

Se o serviço pede um token fixo, ele vai no cabeçalho:

```bash
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 é:

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

```bash
claude mcp add --env AIRTABLE_API_KEY=SUA_CHAVE --transport stdio airtable \
  -- npx -y airtable-mcp-server
```

Um exemplo real com WhatsApp. O [WACrew](https://wacrew.com.br/servidor-mcp-whatsapp/) publica o servidor `wacrew-mcp` no npm, que liga o Claude Code ao painel do WhatsApp:

```bash
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](https://wacrew.com.br/blog/whatsapp-mcp-claude-code/).

## 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 `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:

```json
{
  "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

```bash
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](https://wacrew.com.br/blog/cursor-mcp/) mostra a configuração equivalente no editor.
