Depuração - Documentação Oficial do MCP em Português

Aqui está a tradução do conteúdo para português, mantendo o formato Markdown e as instruções:

Um guia abrangente para depurar integrações do Model Context Protocol (MCP)

A depuração eficaz é essencial ao desenvolver servidores MCP ou integrá-los com aplicativos. Este guia aborda as ferramentas e abordagens de depuração disponíveis no ecossistema MCP.

Este guia é para macOS. Guias para outras plataformas estão chegando em breve.

Visão geral das ferramentas de depuração

O MCP fornece várias ferramentas para depuração em diferentes níveis:

MCP Inspector

Interface de depuração interativa

Teste direto do servidor

Consulte o guia do Inspector para obter detalhes

Claude Desktop Developer Tools

Teste de integração

Coleta de logs

Integração com o Chrome DevTools

Registro do Servidor (Server Logging)

Implementações de registro personalizadas

Rastreamento de erros

Monitoramento de desempenho

Depurando no Claude Desktop

Verificando o status do servidor

A interface do Claude.app fornece informações básicas sobre o status do servidor:

Clique no ícone

para visualizar:

Servidores conectados

Prompts e recursos disponíveis

Clique no ícone

para visualizar:

Ferramentas disponibilizadas para o modelo

Visualizando logs

Revise os logs detalhados do MCP no Claude Desktop:

Os logs capturam:

Eventos de conexão do servidor

Problemas de configuração

Erros de tempo de execução

Trocas de mensagens

Usando o Chrome DevTools

Acesse as ferramentas de desenvolvedor do Chrome dentro do Claude Desktop para investigar erros do lado do cliente:

Crie um arquivo developer_settings.json com allowDevTools definido como true:

Abra o DevTools: Command-Option-Shift-i

Observação: você verá duas janelas do DevTools:

Janela de conteúdo principal

Janela da barra de título do aplicativo

Use o painel Console para inspecionar erros do lado do cliente.

Use o painel Network para inspecionar:

Cargas úteis de mensagens

Tempo de conexão

Problemas comuns

Diretório de trabalho

Ao usar servidores MCP com o Claude Desktop:

O diretório de trabalho para servidores iniciados via claude_desktop_config.json pode estar indefinido (como / no macOS), pois o Claude Desktop pode ser iniciado de qualquer lugar

Sempre use caminhos absolutos em seus arquivos de configuração e .env para garantir uma operação confiável

Para testar servidores diretamente via linha de comando, o diretório de trabalho será onde você executa o comando

Por exemplo, em claude_desktop_config.json, use:

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}

Em vez de caminhos relativos como ./data

Variáveis de ambiente

Os servidores MCP herdam apenas um subconjunto de variáveis de ambiente automaticamente, como USER, HOME e PATH.

Para substituir as variáveis padrão ou fornecer as suas, você pode especificar uma chave env em claude_desktop_config.json:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Inicialização do servidor

Problemas comuns de inicialização:

Problemas de caminho

Caminho incorreto do executável do servidor

Arquivos obrigatórios ausentes

Problemas de permissão

Tente usar um caminho absoluto para command

Erros de configuração

Sintaxe JSON inválida

Campos obrigatórios ausentes

Incompatibilidades de tipo

Problemas de ambiente

Variáveis de ambiente ausentes

Valores de variáveis incorretos

Restrições de permissão

Problemas de conexão

Quando os servidores não conseguem se conectar:

Verifique os logs do Claude Desktop

Verifique se o processo do servidor está em execução

Teste de forma independente com o Inspector

Verifique a compatibilidade do protocolo

Implementando o registro (logging)

Registro do lado do servidor

Ao construir um servidor que usa o stdio transport local, todas as mensagens registradas em stderr (erro padrão) serão capturadas automaticamente pelo aplicativo host (por exemplo, Claude Desktop).

Os servidores MCP locais não devem registrar mensagens em stdout (saída padrão), pois isso interferirá na operação do protocolo.

Para todos os transports, você também pode fornecer registro ao cliente enviando uma notificação de mensagem de log:

Python

TypeScript

Eventos importantes para registrar:

Etapas de inicialização

Acesso a recursos

Execução de ferramentas

Condições de erro

Métricas de desempenho

Registro do lado do cliente

Em aplicativos cliente:

Ative o registro de depuração

Monitore o tráfego de rede

Rastreie as trocas de mensagens

Registre os estados de erro

Fluxo de trabalho de depuração

Ciclo de desenvolvimento

Desenvolvimento inicial

Use o Inspector para testes básicos

Implemente a funcionalidade principal

Adicione pontos de registro

Teste de integração

Teste no Claude Desktop

Monitore os logs

Verifique o tratamento de erros

Testando mudanças

Para testar as alterações de forma eficiente:

Alterações de configuração: Reinicie o Claude Desktop

Alterações no código do servidor: Use Command-R para recarregar

Iteração rápida: Use o Inspector durante o desenvolvimento

Melhores práticas

Estratégia de registro

Registro estruturado

Use formatos consistentes

Inclua contexto

Adicione timestamps

Rastreie IDs de solicitação

Tratamento de erros

Registre rastreamentos de pilha

Inclua o contexto do erro

Rastreie padrões de erro

Monitore a recuperação

Rastreamento de desempenho

Registre o tempo de operação

Monitore o uso de recursos

Rastreie os tamanhos das mensagens

Meça a latência

Considerações de segurança

Ao depurar:

Dados confidenciais

Limpe os logs

Proteja as credenciais

Mascare informações pessoais

Controle de acesso

Verifique as permissões

Verifique a autenticação

Monitore os padrões de acesso

Obtendo ajuda

Ao encontrar problemas:

Primeiros passos

Verifique os logs do servidor

Teste com o Inspector

Revise a configuração

Verifique o ambiente

Canais de suporte

Problemas do GitHub

Discussões do GitHub

Fornecendo informações

Trechos de log

Arquivos de configuração

Passos para reproduzir

Detalhes do ambiente