MCP configurado mas não aparece no Claude Code: como diagnosticar

O servidor está no arquivo, o comando roda na mão, e mesmo assim o Claude Code não lista a ferramenta

Fala aí, beleza? Se tu chegou aqui depois de plugar um MCP e ficar encarando uma sessão que finge que aquele servidor não existe, respira: na maioria dos casos ele não está quebrado

Ele está em outro escopo, ou pendente de aprovação, ou esperando você fazer login

E a diferença entre esses três casos não se adivinha, se lê. É isso que a gente vai fazer aqui: um roteiro de diagnóstico que sai do estado visível e vai até a causa, sem jogar configuração nova por cima da antiga na esperança de acertar

Como ler o estado real da conexão do MCP em 3 comandos:

Antes de editar qualquer arquivo, olhe o que o Claude Code está enxergando

São três leituras diferentes, e cada uma te conta uma parte da história

1. Rode /mcp dentro da sessão. Esse slash command lista todos os servidores configurados, o status de conexão de cada um e se você já aprovou aquele servidor para o projeto atual

O erro comum deste passo: parar por aqui. O /mcp mostra o estado da sessão aberta, não a lista de tudo que você registrou na máquina

2. Rode claude mcp list no shell.

claude mcp list

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

Ele mostra os servidores registrados e o status de cada um. Quando o status é de falha de conexão, o detalhe da falha vem anexado ali mesmo na linha de status

É também na saída dele (e no /mcp) que aparece o aviso de espaço em branco escondido na configuração, sobre o qual eu falo mais pra frente

O erro comum deste passo: rodar de outra pasta. Servidor de escopo local só carrega no projeto onde foi adicionado, então a lista MUDA conforme o diretório em que tu está

3. Peça o detalhe com claude mcp get <nome>.

claude mcp get meu-servidor

Aqui aparece a linha Issue:, com o código HTTP ou de erro mais o texto retornado pelo próprio servidor

O erro comum deste passo: pular ele. Essa linha costuma ser a diferença entre "não conecta" e "o servidor respondeu 401", que são problemas completamente diferentes

E o erro comum do roteiro inteiro: olhar só um dos dois lados (sessão ou shell) e concluir que o servidor não existe 🙂

O servidor nem aparece na lista: você adicionou no escopo errado

Sintoma: nem o /mcp nem o claude mcp list mostram o servidor neste projeto, ou ele simplesmente sumiu quando você trocou de pasta

Causa: o Claude Code tem três escopos de configuração de MCP, gravados em dois arquivos, e você escolhe qual usar pela flag --scope do claude mcp add

Sacou o pulo do gato? Se você não passou --scope, caiu no local, e local mora naquele projeto e só nele

Solução: re-adicione no escopo certo

claude mcp add --transport http meu-servidor --scope user https://exemplo.com/mcp

Como prevenir: se o servidor é do projeto e não seu, use --scope project. O Claude Code cria ou atualiza o .mcp.json sozinho, e esse arquivo deve ser versionado pra que o time inteiro receba as mesmas ferramentas

Você colocou mcpServers no settings.json e nada acontece

Sintoma: o bloco de configuração está escrito, o JSON é válido, zero erro na tela e zero servidor na lista

Causa: a chave mcpServers colocada em settings.json ou settings.local.json é silenciosamente ignorada. Existe issue aberta no repositório do Claude Code, a #24477, justamente pedindo que a documentação avise sobre isso

Ou seja: não é você que digitou errado, é arquivo errado mesmo

Solução: configuração de MCP vive no .mcp.json (escopo project) ou no ~/.claude.json (escopo user)

E o caminho seguro é deixar o próprio claude mcp add escrever o arquivo pra você

Como prevenir: nunca edite um arquivo de configuração à mão só porque o JSON "parece" aceitar a chave. JSON aceita quase tudo, quem tem que aceitar é o programa que lê

Status ‘Pending approval’: o servidor existe, mas você ainda não aprovou

Sintoma: o servidor aparece bonitinho no claude mcp list e no claude mcp get, com o status ⏸ Pending approval, e as ferramentas não entram na sessão

Causa: por segurança, o Claude Code pede aprovação em sessão interativa antes de usar servidores de escopo project vindos do .mcp.json

Faz todo sentido, né? Um .mcp.json versionado pode mandar o agente subir um servidor qualquer, então ele te pergunta antes

A armadilha: a configuração enableAllProjectMcpServers aprova automaticamente todos os servidores definidos no .mcp.json do projeto, MAS ela é ignorada em pasta não confiável

Resultado: um repositório recém clonado não aprova os próprios servidores, e o servidor fica em Pending approval em vez de conectar

Solução: abra uma sessão interativa e aprove

E quando você quiser decidir tudo de novo do zero, existe comando pra zerar as escolhas de aprovação dos servidores de escopo project:

claude mcp reset-project-choices

Servidor remoto pedindo login: 401, 403 e o fluxo OAuth

Sintoma: o servidor até conecta, mas as chamadas de ferramenta falham, ou ele aparece sinalizado no /mcp

Causa: o Claude Code marca um servidor remoto como precisando de autenticação quando o servidor responde 401 Unauthorized ou 403 Forbidden, e o servidor sinalizado no /mcp é justamente o convite pra completar o fluxo OAuth

Com uma ressalva pro 401 em servidor que já estava autenticado, que eu explico logo abaixo

É aqui que a linha Issue: do claude mcp get salva teu tempo, porque ela mostra o código que voltou

Solução: autentique pelo /mcp em sessão interativa, ou direto pelo shell:

claude mcp login meu-servidor

E se o servidor já está conectado, o menu do /mcp oferece a opção Re-authenticate, o que permite entrar de novo ANTES da próxima chamada de ferramenta falhar na tua cara

Detalhe importante: quando uma requisição a um servidor OAuth já autenticado volta 401, o Claude Code renova o token guardado, reconecta e tenta a requisição de novo uma vez

Só se essa nova tentativa também falhar é que ele sinaliza o servidor no /mcp. Então servidor sinalizado ali já é falha que sobreviveu a um retry

Funciona no terminal interativo e falha no claude -p ou no Agent SDK

Sintoma: o mesmo MCP responde lindamente na sessão normal e some na execução automatizada

Causa: em modo não interativo não existe painel /mcp, então o Claude Code não consegue rodar o fluxo OAuth. Sem painel, sem navegador, sem login

Comportamento esperado: em execução com claude -p ou pelo Agent SDK com tool search ligado, ele informa ao Claude que as ferramentas daquele servidor estão indisponíveis até a autorização

O que muda bastante o debug, porque o modelo pode nomear o servidor que precisa de login em vez de responder como se ele nem estivesse configurado

Solução: autorize ANTES, em sessão interativa pelo /mcp, ou pelo claude mcp login <nome> no shell, e só depois dispare a automação

O servidor stdio não sobe ou estoura o tempo: timeout e comando de inicialização

Sintoma: falha de conexão logo na primeira tentativa, principalmente em servidor local

Causa 1, o relógio: o timeout padrão de inicialização de servidor MCP é de 30 segundos. Dá pra configurar esse tempo em milissegundos pela variável de ambiente MCP_TIMEOUT:

MCP_TIMEOUT=10000 claude

Causa 2, o download: a primeira execução de um servidor stdio pode demorar porque o npx ainda está baixando os pacotes

Ou seja, aquela primeira subida lenta às vezes não é bug, é a internet trabalhando. Tenta de novo antes de sair reescrevendo tudo

Causa 3, a sintaxe: para servidor local stdio não existe flag --transport, porque stdio é o transporte padrão. O comando é assim:

claude mcp add meu-servidor -- npx -y algum-pacote-mcp

Tudo depois do separador -- é o comando que o Claude Code executa pra subir o servidor, e vai passado sem alteração nenhuma. Se o comando não roda sozinho no teu terminal, ele também não vai rodar ali

E se o Claude Code já vinha te dando trabalho antes disso, vale checar os erros comuns na instalação do Claude Code, porque Node e permissão quebrados derrubam servidor stdio também

Bônus pra ferramenta lenta: dá pra definir timeout de execução de ferramenta por servidor, com o campo timeout em milissegundos na entrada daquele servidor no .mcp.json, sobrescrevendo o MCP_TOOL_TIMEOUT só pra ele

{
  "mcpServers": {
    "meu-servidor": {
      "timeout": 600000
    }
  }
}

Espaço em branco escondido na configuração:

Sintoma: caminho, URL ou chave de API aparentemente corretos, você lê dez vezes, tudo certo, e a conexão não fecha

Causa: o clássico do copiar e colar, um espaço no começo ou no fim do valor

Já me ferrei uma vez por causa disso, e a boa notícia é que o Claude Code te avisa: ele checa command, url, cada item de args e as chaves e valores de env e headers

O aviso sai na saída do claude mcp list e no /mcp

Solução: leia o aviso ANTES de reescrever a configuração inteira. Ele já aponta o campo

Como prevenir: deixe o claude mcp add gravar o valor em vez de colar direto no arquivo

O servidor conecta mas o Claude não usa a ferramenta: permissão e política da organização

Sintoma: status conectado no /mcp, tudo verde, e a ferramenta nunca é chamada, ou é bloqueada na hora do uso

Causa 1, regra de permissão. Ferramentas de MCP seguem o padrão mcp__<nome-do-servidor>__<nome-da-ferramenta>

E tem uma pegadinha aí: o glob só vale no trecho do nome da ferramenta, depois do prefixo literal mcp__<servidor>__

mcp__puppeteer__*
mcp__github__get_*

O padrão precisa casar com o nome completo. Em regras de deny e ask, casa com toda ferramenta e mcp__ bloqueia toda ferramenta MCP de todos os servidores de uma vez, então uma regra dessas esquecida em algum lugar mata teu servidor mesmo com ele conectado

Causa 2, política de administrador. Administradores podem restringir quais servidores MCP rodam na organização via managed-mcp.json, incluindo desligar MCP por completo, e filtrar o que o usuário configura com allowedMcpServers e deniedMcpServers

Se você está em máquina da empresa e nada do que tu faz muda o resultado, essa é uma hipótese que vale levantar com quem administra

Como isolar se o problema é do servidor ou do Claude Code:

Quando os comandos de status não bastam, é hora de olhar o que o servidor está cuspindo

1. Suba o Claude Code em modo debug de MCP.

claude --debug=mcp

2. Leia o stderr do servidor no arquivo de log de debug da sessão, em ~/.claude/debug/<session-id>.txt

3. Interprete assim: se o erro vem do servidor (log com falha própria dele, ou linha Issue: trazendo o texto retornado pelo servidor), o alvo é o servidor, e você vai debugar ele fora do Claude Code

4. Se não há nada do servidor no log, o alvo é a configuração no lado do Claude Code: escopo, arquivo, aprovação, permissão. Volta pro começo deste post e segue a ordem

O erro comum deste roteiro: mexer nos dois lados ao mesmo tempo. Muda uma coisa, roda claude mcp list, olha o status, e só então muda a próxima

E lembra que nem todo MCP é servidor local: serviços como Sentry, Linear e Notion hospedam servidores atrás de OAuth, onde você adiciona a URL e faz o login pelo navegador

Nesses casos o "problema" quase sempre é login, não configuração, e isso vale até pra quem está usando o Claude Code sem programar e só quer plugar as ferramentas do dia a dia

Conclusão

A ordem que resolve a maior parte dos casos é sempre a mesma: status, escopo, aprovação, autenticação, timeout, permissão

Status com /mcp e claude mcp list, escopo comparando local, project e user, aprovação pro .mcp.json, autenticação pros 401 e 403, timeout pro stdio que não sobe e permissão pro servidor que conecta mas nunca é chamado

Próximo passo prático: roda claude mcp list agora mesmo, compara o escopo do servidor com o projeto que tu tem aberto e, se o status for de falha, vai direto no claude mcp get <nome> pra ler a linha Issue:

Uma última: autenticar servidor MCP direto pelo shell com claude mcp login é recurso que apareceu no changelog do Claude Code

Então se esse comando não existir aí na tua máquina, olha a versão instalada antes de achar que é outro problema 😀

até o próximo post!