Claude Code MCP Logs: Encontre a Primeira Fronteira Falhada

Se você está procurando por Claude Code MCP logs , comece pelo estado resolvido do servidor e depois capture um arquivo de depuração com escopo de incidente. Não comece seguindo o diretório de log Claude Desktop: a documentação atual da MCP rotulou esses caminhos do sistema de arquivos especificamente para o Desktop, enquanto Claude Code documentos /mcp , claude mcp list , claude debug mcp e debug file . O resultado útil não é "encontrar um tronco". É para identificar o primeiro limite falho: configuração, aprovação do projeto, início do processo, descoberta de ferramentas, execução de ferramenta ou o resultado externo que a ferramenta deveria produzir. Um tronco pode explicar uma fronteira. Não pode provar todos os seis. Este guia utiliza a documentação atual do Claude Code e o 2.1.220 de lançamento do NPM, verificados em 30 de julho de 2026. Fixe sua versão instalada em todos os incidentes porque MCP comportamento e diagnósticos ainda estão mudando. Inspecionar o estado resolvido antes de ler a saída bruta Execute essas verificações a partir do mesmo diretório de trabalho e da mesma conta de usuário que apresentou o problema: Dentro da sessão Claude Code afetada, execute: O Guia oficial de configuração e depuração Diz /mcp mostra servidores configurados, status de conexão e aprovação do projeto. O MCP referência Adiciona dois detalhes operacionais que importam: um servidor .mcp.json com escopo de projeto pode permanecer pendente até que o espaço de trabalho seja confiável e o servidor seja aprovado; Um servidor conectado ainda pode expor zero ferramentas, e /mcp relatórios que contam. Esses fatos eliminam três classes de busca cego de registro: Evidências resolvidas Primeira decisão Por que os registros não são os primeiros Servidor ausente CONFIG MISSING Ainda não existe um processo servidor carregado para diagnosticar. Verifique as fontes de escopo e configurações. Aguardando aprovação APPROVAL WAIT Esse é um limite legítimo de autoridade, não um acidente. Revise e aprove de forma interativa. Falhou em conectar Captura MCP evidência de depuração O comando, caminho, ambiente, autenticação ou transporte podem ter falhado. Conectado, zero ferramentas Reconecte, depois capture MCP evidência de depuração A startup teve sucesso suficiente para se conectar, mas a descoberta não produziu um registro utilizável. Conectado, ferramentas presentes Reproduzir uma chamada limitada A saúde da conexão não diz nada sobre a ferramenta selecionada ou seu efeito externo. Caminhos relativos merecem especial suspeita para servidores stdio locais. Claude Code documentos que command e args caminhos resolvem a partir do diretório onde Claude Code foi lançado, não da localização de .mcp.json . Um servidor pode, portanto, funcionar em um repositório e falhar em outro com texto de configuração idêntico. Capturar um arquivo de depuração de Claude Code MCP com escopo A atualidade Claude Code Referência CLI documenta duas bandeiras relevantes: debug ativa o modo de depuração e aceita filtros de categoria como mcp ; debug file <path escreve a saída de depuração em um caminho explícito e ativa implicitamente o modo de depuração. Crie um diretório privado de incidentes, inicie uma sessão nova apenas com a categoria de depuração MCP e reproduza um sintoma limitado: Durante essa sessão, inspecione /mcp . Se um servidor estiver conectado sem nenhuma ferramenta, use a ação de Reconectar uma vez. Se houver ferramentas presentes, invoque apenas a menor ferramenta de somente leitura que reproduza o problema. Não tente novamente uma chamada com capacidade de gravação apenas para tornar o log mais interessante. Trate o arquivo de depuração como sensível. Ele pode conter caminhos absolutos, nomes de servidores, detalhes do ambiente, metadados de requisições ou padrão de servidor. Registre as evidências derivadas no recibo do incidente e depois mantenha ou exclua o arquivo bruto conforme sua política de segurança. Não copie tokens de acesso, corpos de prompts, argumentos de ferramentas, resultados ou texto stderr para um sistema de monitoramento só porque o arquivo os contém. Um público Claude Code solicitação de recurso para arquivos de log por MCP servidor relata que os usuários querem arquivos persistentes no estilo Desktop para Claude Code. Essa questão é uma evidência útil de limites, não uma garantia de produto. O procedimento de incidente suportado deve depender do arquivo de depuração explícito documentado, não de um caminho padrão assumido por servidor. Compare o caminho das evidências com o transporte O MCP guia de depuração para revisão do protocolo 2026 07 28 traça uma fronteira crucial de transporte. Para um servidor local stdio , o stdout transporta mensagens de protocolo. Diagnósticos de servidor pertencem ao stderr; Escrever texto de diagnóstico no STDOUT pode corromper o fluxo do protocolo. O guia de solução de problemas da Claude Code recomenda especificamente claude debug mcp quando um servidor conectado não expõe nenhuma ferramenta, pois isso torna o stderr do servidor disponível nas evidências de depuração. Para Streamable HTTP , o cliente não pode capturar o stderr do processo do servidor remoto. Um arquivo de depuração Claude Code ainda pode mostrar o comportamento de conexão e requisição do lado do cliente, mas a falha interna do servidor precisa de logs do lado do servidor ou OpenTelemetry além de inspeção em nível HTTP. Um segmento de depuração vazio do cliente não é prova de que o serviço remoto não fez nada. Essa distinção impede uma conclusão errada comum: Registre o transporte no recibo. Sem ele, "sem stderr" é ambíguo. Construa um recebimento de incidentes minimizado por conteúdo O tronco bruto é evidência para investigação. O recibo é o prontuário de saúde duradouro. Pode continuar sendo útil sem armazenar conteúdo: Mantenha explícita a precedência do classificador: Repeti essa regra contra oito casos sintéticos. Ele separou corretamente configuração ausente, espera de aprovação, falha de inicialização capturada, ferramentas conectadas zero, erro de ferramenta, resposta bem sucedida da ferramenta sem resultado, resultado verificado e conexão falhada com evidência de depuração insuficiente. Todos os oito estados esperados foram aprovados. Os dois últimos casos são o limite importante. Um resultado JSON RPC de sucesso ou não erro é a evidência de atividade. Se a tarefa prometeu um problema criado, registro alterado, arquivo entregue ou destino atualizado, verifique esse destino separadamente. Sem esse recibo, o estado correto é OUTCOME UNVERIFIED , não saudável. Escolha a menor ação segura próxima Cada estado deve levar a uma resposta limitada: CONFIG MISSING : inspecionar o escopo das configurações e o arquivo exato Claude Code carregado. Não altere o código do servidor. APPROVAL WAIT : Encaminhar a aprovação para o humano responsável. Não descreva a espera como um crash. STARTUP FAILED : repare a primeira causa de inicialização de concreto na evidência de depuração com escopo, depois reconecte uma vez. DISCOVERY EMPTY : compare as evidências de inicialização e da lista de ferramentas; Teste o servidor de forma independente com MCP Inspector se necessário. TOOL CALL FAILED : Preserve a identidade da solicitação, identifique se a tentativa é segura e evite repetir uma escrita incerta. OUTCOME UNVERIFIED : consultar o destino por identificador estável. Não execute a ferramenta novamente até saber se o efeito já aconteceu. UNCERTAIN : Colete as evidências de limites que faltam ou escale. Desconhecido é um estado operacional, não um convite para adivinhar. HEALTHY : exigem tanto uma cadeia de MCP utilizável quanto um recibo de resultado novo e determinístico. Os registros explicam uma falha. Status resolvido torna o local localizável. Um recibo de destino torna a recuperação verificável. Mantenha esses trabalhos separados, e um incidente Claude Code MCP se torna um exercício curto de evidências, em vez de uma sequência de tentativas cada vez mais arriscadas. Sidewisp é projetado em torno dessa distinção que prioriza a saúde entre conexão, progresso útil, ferramentas e resultados. A Sidewisp está atualmente em prévia privada. Os adaptadores de monitoramento de produção e o executor de recuperação geralmente não são enviados.