Configuração MCP do Claude Code: .mcp.json, escopos e solução de problemas

O formato do .mcp.json

Um arquivo de projeto com um servidor remoto e um servidor local se parece com isso:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

O campo type é obrigatório sempre que url está presente. Um url sem type é reportado como um erro de configuração (a mensagem diz para adicionar "type": "http", ou sse ou ws), o que substituiu uma reclamação mais antiga e muito menos útil sobre um command ausente. O valor streamable-http é aceito como um apelido de http. Um servidor remoto que precisa de uma credencial fixa recebe um objeto headers; um local recebe command, args e env. O timeout opcional é um limite por chamada de ferramenta em milissegundos. Servidores WebSocket só podem ser declarados em um arquivo ou por meio de claude mcp add-json; a flag --transport não aceita ws.

O comando claude mcp add com --scope project escreve esse arquivo para você, então a edição manual só é necessária para campos que o comando não expõe ou quando você prefere revisar a mudança em um pull request.

Mantendo segredos fora do arquivo

Como o .mcp.json é feito para ser commitado, tokens não deveriam ser digitados nele. O Claude Code expande variáveis de ambiente em command, args, env, url e headers: ${VAR} pega o valor da variável, e ${VAR:-default} recorre ao padrão quando ela não está definida.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Uma variável referenciada que não está definida e não tem um padrão não impede o servidor de carregar; o texto literal ${API_KEY} é enviado como está, e claude mcp list imprime um aviso. Esse aviso é a primeira coisa a procurar quando um servidor conecta mas toda chamada é rejeitada como não autorizada.

Para um servidor que suporta OAuth não há nada para esconder: deixe a entrada só com type e url, e cada usuário faz login uma vez pelo /mcp. O token é armazenado por usuário, fora do repositório, e removido de novo por claude mcp remove.

Aprovação, precedência e servidores gerenciados

Na primeira vez que o Claude Code vê um servidor no .mcp.json de um projeto, uma sessão interativa pergunta se deve usá-lo; execuções não interativas (claude -p, o Agent SDK, sessões na nuvem) o carregam sem perguntar. A decisão é lembrada por projeto; claude mcp reset-project-choices a esquece para que você possa aprovar de novo depois de uma mudança.

Quando um nome é definido em vários lugares, a ordem é escopo local, depois escopo de projeto, depois escopo de usuário, depois servidores que plugins fornecem, depois conectores do claude.ai. A entrada vencedora inteira é usada. Organizações podem impor uma lista fixa de servidores por meio de um arquivo de configuração gerenciada ou da configuração managedMcpServers (Claude Code 2.1.259 ou posterior); esses ficam acima de todo escopo de nível de usuário, e um arquivo gerenciado que reivindica controle exclusivo faz o claude mcp add recusar com uma mensagem dizendo que a configuração empresarial está ativa. Listas de permissão e negação (allowedMcpServers, deniedMcpServers) também podem restringir quais URLs ou comandos os usuários podem adicionar, e uma negação sempre vence.

Lendo a saída de status

O claude mcp list reporta cada servidor como conectado, precisa de autenticação, falhou ao conectar, aguardando aprovação, rejeitado por disabledMcpjsonServers, ou desativado para esse projeto. Alguns avisos menos óbvios que ele imprime valem a pena conhecer: espaço em branco oculto no início ou fim de um valor (um token colado que terminou com uma quebra de linha), o mesmo nome apontando para endpoints diferentes em dois escopos, e um punhado de nomes reservados que não podem ser usados para os seus próprios servidores. Servidores WebSocket não aparecem na lista de forma alguma; verifique-os com claude mcp get <nome> ou /mcp.

Falhas comuns e as correções delas

1. Um servidor remoto mostra "precisa de autenticação" ou responde 401 ou 403. Abra /mcp, selecione o servidor e complete o login pelo navegador, ou rode claude mcp login <nome>. Se o servidor usa um token estático, verifique o valor do cabeçalho e o aviso sobre variáveis não expandidas.
2. Um servidor local falha ao conectar na inicialização. Rode o comando dele manualmente no mesmo shell para ver o erro real; as causas usuais são um runtime ausente, um pacote que precisa ser instalado, ou uma variável de ambiente obrigatória. Servidores lentos para iniciar atingem o limite de inicialização, que MCP_TIMEOUT aumenta em milissegundos, por exemplo MCP_TIMEOUT=10000 claude.
3. O servidor conecta mas uma ferramenta devolve um resultado truncado. A saída de ferramenta tem um teto de 25.000 tokens por padrão, com um aviso a partir de 10.000; MAX_MCP_OUTPUT_TOKENS aumenta o teto.
4. Ferramentas parecem estar ausentes da conversa. O Claude Code adia as definições de ferramenta até que sejam necessárias para manter o contexto pequeno, então só nomes e instruções de servidor carregam no início; o assistente ainda as encontra quando um pedido combina. Defina "alwaysLoad": true em uma entrada de servidor se você quiser que as definições completas dele estejam presentes desde a primeira mensagem.
5. Um servidor remoto cai no meio da sessão. O Claude Code tenta reconectar uma conexão caída até cinco vezes com atrasos crescentes e uma primeira conexão HTTP falhada até três vezes, mas não para erros de autenticação e não para servidores locais, então uma falha de autenticação não vai se corrigir sozinha.

Testando a configuração contra um serviço ao vivo

O jeito mais rápido de validar o .mcp.json de um projeto é um servidor cujas respostas você consegue conferir de forma independente. Com { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } commitado e cada desenvolvedor logado uma vez pelo /mcp, um pedido como "rode uma verificação HTTP na nossa URL de staging a partir da Europa e da Ásia" precisa voltar com códigos de status e tempos de resposta reais dos pontos de verificação da HostTracker, o que ou prova que o arquivo está sendo lido corretamente ou estreita a falha para o login. O guia complementar, como adicionar um servidor MCP ao Claude Code, cobre o caminho da linha de comando e os escopos em mais detalhe.