Servidor MCP não aparece no Claude Code: por onde começar o diagnóstico

Servidor adicionado, o comando rodou sem reclamar de nada, e aí você abre a sessão e as ferramentas simplesmente não estão lá 😅

O reflexo quase automático é remover tudo e instalar de novo, na fé de que na segunda vez cola

Só que reinstalar é o caminho mais lento, porque apaga a pista antes de você ler a pista

Existe uma ordem de checagem que separa, em poucos minutos, dois problemas MUITO diferentes: configuração errada (escopo, aprovação, caminho, transporte) e servidor quebrado de verdade (não sobe, não autentica, não devolve as ferramentas)

Se você ainda está entendendo o que são servidores MCP e quando eles valem a pena, o texto ajuda a dar contexto antes do diagnóstico

Bora ao roteiro?

Ler o status antes de mexer em qualquer coisa: o que cada resultado do claude mcp list significa

O primeiro comando não é de correção, é de leitura:

claude mcp list

Ele mostra um status ao lado de cada servidor configurado, e são três possibilidades

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Aqui mora o mal-entendido mais comum do troubleshooting: muita gente lê o ✘ Failed to connect como se o comando de listagem tivesse falhado

Não é isso

O ✘ Failed to connect é um diagnóstico DO SERVIDOR, não do comando claude mcp list, como resume esta leitura do status do claude mcp list

Ou seja: a listagem funcionou perfeitamente e está te contando que o servidor não subiu

Dentro da sessão existe o equivalente visual disso, o comando de barra /mcp

Ele mostra todos os servidores configurados, o status de conexão e se você já aprovou aquele servidor para o projeto atual

Prevenção: sempre cheque o status antes de repetir o claude mcp add

Repetir o add sem ler o status é como apertar o botão do elevador várias vezes, não muda nada e ainda te faz perder a informação de qual era o erro 🙂

O servidor sumiu porque foi gravado no escopo errado

Sintoma: o servidor existe em um projeto e não existe em outro, ou some quando você troca de pasta

Causa: o claude mcp add grava em escopo local por padrão

Escopo local significa gravado em ~/.claude.json sob o caminho daquele projeto, ou seja, privado e ativo apenas no projeto atual

Então não sumiu nada, ele nunca esteve no outro projeto

O Claude Code tem três escopos de configuração de servidor MCP, e a escolha do escopo define em quais projetos o servidor carrega:

• local: padrão, gravado em ~/.claude.json sob o caminho daquele projeto
• project: arquivo .mcp.json na raiz do projeto, compartilhado com o time
• user: gravado em ~/.claude.json, disponível em todos os projetos da máquina

Solução: decidir o escopo na hora de adicionar

claude mcp add --scope project <nome> <comando>
claude mcp add --scope user <nome> <comando>

E tem um detalhe que explica sumiço estranho: quando dois escopos definem servidores com o MESMO nome, existe uma ordem de precedência

local > project > user

Então um servidor local com nome repetido silencia o do .mcp.json do time, e você fica olhando pro arquivo do projeto sem entender por que a configuração dele não vale

Prevenção: escolha o escopo no momento do add, não depois, e evite nome repetido entre escopos

Servidor do .mcp.json aparece desabilitado: falta a aprovação do projeto

Sintoma: o servidor do time está listado, mas desconectado e sem ferramenta nenhuma

Causa: servidores de escopo project, vindos do .mcp.json, exigem aprovação interativa uma única vez, por segurança

Faz sentido, né?

Um arquivo que veio no repositório pode mandar o seu Claude Code rodar um comando qualquer na sua máquina, então ele não sai executando por conta própria

Enquanto não aprovado, o servidor aparece como pendente de aprovação e desabilitado

Solução: a aprovação é dada pelo painel /mcp, dentro da sessão

E se a escolha anterior travou o servidor (você rejeitou sem querer, por exemplo), existe um comando dedicado pra resetar as escolhas de aprovação e rejeição dos servidores de escopo project no projeto atual:

claude mcp reset-project-choices

Prevenção: avise o time que o primeiro uso pede aprovação

Isso economiza uma thread inteira de "o MCP tá quebrado aqui" no chat da equipe 😀

Status Needs authentication: credencial recusada em servidor remoto

Sintoma: ! Needs authentication no claude mcp list

Causa: autenticação OAuth pendente ou credencial não aceita pelo servidor remoto

Solução: o painel /mcp é onde se faz a autenticação OAuth de servidores remotos, e é também de lá que se reconecta um servidor

Pra checar o que está configurado naquele servidor específico:

claude mcp get <nome>

Ele mostra os detalhes do servidor, incluindo se há credenciais OAuth configuradas

Prevenção: não deixe credencial hardcoded no arquivo que vai pro repositório

O .mcp.json suporta expansão de variáveis de ambiente

Em servidores stdio, os valores sensíveis vão no bloco env:

"env": {
  "API_KEY": "${STRIPE_API_KEY}"
}

Em servidores HTTP, os headers também suportam expansão de variável de ambiente

Assim o arquivo do time descreve a configuração e cada máquina traz a própria chave

Failed to connect: o servidor nem sobe

Esse é o status que mais assusta e o que mais tem causa boba

Sintoma: ✘ Failed to connect

Causa 1: caminho relativo em command ou args

Essa é campeã

O caminho é resolvido contra o diretório de onde o Claude Code foi iniciado, e NÃO contra a localização do .mcp.json

Ou seja: funciona quando você abre a sessão na raiz do projeto e quebra quando você abre dentro de uma subpasta

Usar caminho absoluto em command e args evita a falha

Causa 2: transporte errado pro que o servidor entrega

A escolha do transporte depende do que a documentação do servidor te dá: um comando pra rodar ou uma URL

Comando local usa stdio, que é o transporte padrão, sem flag --transport

URL usa HTTP ou SSE:

claude mcp add --transport http <nome> <url>

Tentar adicionar uma URL como se fosse comando local é receita certa de falha na conexão

Causa 3: servidor lento pra inicializar

Dá pra ajustar o tempo de espera de inicialização do servidor MCP por variável de ambiente, em milissegundos:

MCP_TIMEOUT=10000 claude

Prevenção: caminho absoluto sempre, e leia na doc do servidor se ele é comando ou URL antes de montar o add

E se depois dessas três o status continuar em ✘ Failed to connect, não fica no chute: o motivo real do erro sai no log de depuração, que é exatamente a próxima seção

Conectado, mas com zero ferramentas na lista

Sintoma: status verde, bonitinho, e nenhuma tool disponível pro modelo usar

Causa: o servidor subiu com sucesso, porém não está devolvendo a lista de tools

Repara que esse caso é o oposto do anterior: a conexão deu certo, o conteúdo é que não veio

Solução imediata: escolher Reconnect no painel /mcp

E tem um contexto técnico que explica bastante servidor caseiro nessa situação

A especificação do MCP proíbe que um servidor stdio escreva no stdout qualquer coisa que não seja mensagem MCP válida, como está na spec de transportes do MCP

O servidor PODE escrever strings UTF-8 no stderr para log, e o cliente pode capturar, encaminhar ou ignorar esse log

Então aquele print de debug esquecido no meio do seu servidor não é inofensivo: ele entra no mesmo canal da comunicação e quebra a conversa

Prevenção: stdout limpo em servidores próprios, log sempre no stderr

Tome cuidado com bibliotecas que logam sozinhas no stdout também, elas fazem a mesma bagunça sem você escrever uma linha

Agora, atenção num detalhe que muita gente confunde: stdout poluído é a explicação pro servidor QUE É SEU e vive nesse estado

Se o servidor é de terceiro, registra um monte de ferramenta e o sumiço vai e volta sozinho, a causa provável é outra, e ela tem seção própria mais abaixo (a da falha silenciosa)

Como ler o log de depuração do MCP quando o status não explica

Quando o status diz que falhou mas não diz POR QUE, é hora de abrir o log

1. Rode o Claude Code com o log de depuração focado em MCP, como mostra a documentação de depuração de configuração:

claude --debug=mcp

O erro comum deste passo: rodar o comando normal e esperar que a mensagem de erro apareça na tela da sessão

2. Reproduza o problema na sessão, ou seja, deixe o servidor tentar conectar de novo

O erro comum deste passo: mexer na configuração antes de reproduzir, e aí você não sabe mais qual versão gerou qual log

3. Abra o arquivo de log, gravado em ~/.claude/debug/<session-id>.txt

O erro comum deste passo: procurar a causa no stdout do servidor em vez de ler o arquivo de log

4. Procure no arquivo a saída de erro do servidor, que pela spec sai no stderr

É ali que costuma estar a frase que resolve tudo: módulo não encontrado, caminho inexistente, variável de ambiente vazia, credencial recusada

5. Corrija UMA coisa por vez e volte pro claude mcp list pra ver se o status mudou

O erro comum deste passo: alterar escopo, caminho e transporte de uma vez só, e depois não saber o que consertou (ou o que quebrou de novo)

Quando o problema não é seu: falha silenciosa em servidores com muitas ferramentas

Nem todo sumiço é erro de configuração, e vale saber disso antes de você virar a noite mexendo em arquivo que estava certo

Existe uma issue reportada no repositório oficial do Claude Code, a issue #38462, descrevendo servidores MCP que registram muitas ferramentas falhando de forma intermitente na conexão de startup

O detalhe cruel: nesse relato o servidor é descartado em silêncio pela sessão inteira, sem mensagem de erro ao usuário

O sinal de alerta pra esse tipo de caso é a INTERMITÊNCIA

Se a mesma configuração, sem você tocar em nada, ora funciona e ora não, o problema provavelmente não está no seu .mcp.json

Nesse cenário, reinstalar não é diagnóstico, é sorteio

E se o que sumiu não for um servidor MCP e sim uma ferramenta instalada na máquina, a lógica de investigação é bem parecida: dá pra ver isso no diagnóstico do Ponytail no Claude Code

Resumo do roteiro de diagnóstico

A ordem enxuta, pra você colar em algum lugar e parar de reinstalar por reflexo:

1. Status primeiro: claude mcp list e classifique em ✔ Connected, ! Needs authentication ou ✘ Failed to connect
2. Painel /mcp: aprovação do projeto, autenticação OAuth e reconexão moram todos ali
3. Escopo: local (padrão, só naquele projeto), project (.mcp.json do time) ou user (toda a máquina), lembrando da precedência local > project > user
4. Caminho e transporte: caminho absoluto em command e args, stdio pra comando local e --transport http pra URL
5. Zero ferramentas com status verde: Reconnect no /mcp e stdout limpo no servidor, e se o sumiço for intermitente, olhe a issue #38462 antes de culpar sua configuração
6. Log por último: claude --debug=mcp e o arquivo em ~/.claude/debug/<session-id>.txt

Próximo passo é bem direto: roda o claude mcp list agora, olha o status e classifica o teu servidor em um dos três antes de apagar qualquer configuração

Na maioria das vezes o servidor MCP não aparece no Claude Code por um motivo chato e simples de arrumar, e o status já te entrega qual é 😀

até o próximo post!