{"meta":{"title":"Guia de depuração do servidor MCP","intro":"Este guia aborda técnicas de depuração específicas para servidores MCP (Protocolo de Contexto de Modelo) ao usar o SDK do Copilot.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/troubleshooting","title":"Solução de problemas"},{"href":"/pt/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"Depuração do MCP"}],"documentType":"article","redirectedFrom":"/pt/copilot/how-tos/copilot-sdk/troubleshooting/debug-mcp-servers"},"body":"# Guia de depuração do servidor MCP\n\nEste guia aborda técnicas de depuração específicas para servidores MCP (Protocolo de Contexto de Modelo) ao usar o SDK do Copilot.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Sumário\n\n* [Diagnóstico Rápido](#quick-diagnostics)\n* [Testando servidores MCP de forma independente](#testing-mcp-servers-independently)\n* [Problemas comuns](#common-issues)\n* [Problemas específicos da plataforma](#platform-specific-issues)\n* [Depuração avançada](#advanced-debugging)\n\n## Diagnóstico rápido\n\n### Checklist\n\nAntes de mergulhar fundo, verifique estes conceitos básicos:\n\n* [ ] O executável do servidor MCP existe e é executável\n* [ ] O caminho do comando está correto (use caminhos absolutos quando estiver em dúvida)\n* [ ] As ferramentas estão habilitadas (`tools: [\"*\"]` ou nomes de ferramentas específicos)\n* [ ] O servidor implementa o protocolo MCP corretamente (responde a `initialize`)\n* [ ] Nenhum firewall/antivírus bloqueando o processo (Windows)\n\n### Habilitar o registro em log de depuração do MCP\n\nAdicione variáveis de ambiente à configuração do servidor MCP:\n\n```typescript\nmcpServers: {\n  \"my-server\": {\n    type: \"local\",\n    command: \"/path/to/server\",\n    args: [],\n    env: {\n      MCP_DEBUG: \"1\",\n      DEBUG: \"*\",\n      NODE_DEBUG: \"mcp\",  // For Node.js MCP servers\n    },\n  },\n}\n```\n\n## Testar servidores MCP de forma independente\n\nSempre teste seu servidor MCP fora do SDK primeiro.\n\n### Teste de protocolo manual\n\nEnviar uma solicitação `initialize` por meio de stdin:\n\n```bash\n# Unix/macOS\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n\n# Windows (PowerShell)\n'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | C:\\path\\to\\your\\mcp-server.exe\n```\n\n**Resposta esperada:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"your-server\",\"version\":\"1.0\"}}}\n```\n\n### Lista de ferramentas de teste\n\nApós a inicialização, solicite a lista de ferramentas:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**Resposta esperada:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### Script de teste interativo\n\nCrie um script de teste para depurar interativamente o servidor MCP:\n\n```bash\n#!/bin/bash\n# test-mcp.sh\n\nSERVER=\"$1\"\n\n# Initialize\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n\n# Send initialized notification\necho '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}'\n\n# List tools\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'\n\n# Keep stdin open\ncat\n```\n\nUso:\n\n```bash\n./test-mcp.sh | /path/to/mcp-server\n```\n\n## Problemas comuns\n\n### Servidor não iniciado\n\n**Sintomas:** Nenhuma ferramenta é exibida, nenhum erro nos logs.\n\n**Causas & Soluções:**\n\n| Cause                              | Solução                                             |\n| ---------------------------------- | --------------------------------------------------- |\n| Caminho de comando incorreto       | Use o caminho absoluto: `/usr/local/bin/server`     |\n| Falta permissão executável         | Execute `chmod +x /path/to/server`                  |\n| Dependências ausentes              | Verificar com `ldd` (Linux) ou executar manualmente |\n| Problemas no diretório de trabalho | Definir `cwd` em configuração                       |\n\n**Depurar executando manualmente:**\n\n```bash\n# Run exactly what the SDK would run\ncd /expected/working/dir\n/path/to/command arg1 arg2\n```\n\n### O servidor é iniciado, mas as ferramentas não aparecem\n\n**Sintomas:** O processo do servidor é executado, mas nenhuma ferramenta está disponível.\n\n**Causas & Soluções:**\n\n1. **Ferramentas não habilitadas na configuração:**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **O servidor não expõe ferramentas:**\n   * Teste manualmente com a requisição `tools/list`\n   * Verificar se o servidor implementa o método `tools/list`\n\n3. **Falha no handshake de inicialização:**\n   * O servidor deve responder a `initialize` corretamente\n   * O servidor deve manipular `notifications/initialized`\n\n### Ferramentas listadas, mas nunca chamadas\n\n**Sintomas:** As ferramentas aparecem em logs de depuração, mas o modelo não as usa.\n\n**Causas & Soluções:**\n\n1. ```\n             **O prompt não precisa claramente da ferramenta:**\n   ```\n\n   ```typescript\n   // Too vague\n   await session.sendAndWait({ prompt: \"What's the weather?\" });\n\n   // Better - explicitly mentions capability\n   await session.sendAndWait({ \n     prompt: \"Use the weather tool to get the current temperature in Seattle\" \n   });\n   ```\n\n2. **Descrição da ferramenta não clara:**\n\n   ```typescript\n   // Bad - model doesn't know when to use it\n   { name: \"do_thing\", description: \"Does a thing\" }\n\n   // Good - clear purpose\n   { name: \"get_weather\", description: \"Get current weather conditions for a city. Returns temperature, humidity, and conditions.\" }\n   ```\n\n3. **Problemas de esquema de ferramenta:**\n   * Garantir `inputSchema` que o esquema JSON seja válido\n   * Os campos necessários devem estar na `required` matriz\n\n### Erros de tempo limite\n\n**Sintomas:**`MCP tool call timed out` Erros.\n\n**Soluções**:\n\n1. **Aumentar o tempo limite:**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **Otimizar o desempenho do servidor:**\n   * Adicionar registro em log de progresso para identificar gargalo\n   * Considere operações assíncronas\n   * Verificar se há bloqueio de E/S\n\n3. **Para ferramentas de longa execução**, considere as respostas de streaming se houver suporte.\n\n### JSON-RPC erros\n\n**Sintomas:** Erros de análise, erros de solicitação inválidos.\n\n**Causas comuns:**\n\n1. **O servidor grava no stdout incorretamente:**\n   * Saída de depuração sendo enviada para stdout em vez de stderr\n   * Linhas adicionais ou espaço em branco\n   ```typescript\n   // Wrong - pollutes stdout\n   console.log(\"Debug info\");\n\n   // Correct - use stderr for debug\n   console.error(\"Debug info\");\n   ```\n\n2. **Problemas de codificação:**\n   * Garantir a codificação UTF-8\n   * Sem BOM (Marca de ordem dos bytes)\n\n3. **Enquadramento de mensagem:**\n   * Cada mensagem deve ser um objeto JSON completo\n   * Delimitado por nova linha (uma mensagem por linha)\n\n## Problemas específicos da plataforma\n\n### Windows\n\n#### .NET aplicativos/ferramentas de console\n\n<!-- docs-validate: hidden -->\n\n```csharp\nusing GitHub.Copilot;\n\npublic static class McpDotnetConfigExample\n{\n    public static void Main()\n    {\n        var servers = new Dictionary<string, McpServerConfig>\n        {\n            [\"my-dotnet-server\"] = new McpStdioServerConfig\n            {\n                Command = @\"C:\\Tools\\MyServer\\MyServer.exe\",\n                Args = new List<string>(),\n                WorkingDirectory = @\"C:\\Tools\\MyServer\",\n                Tools = new List<string> { \"*\" },\n            },\n            [\"my-dotnet-tool\"] = new McpStdioServerConfig\n            {\n                Command = \"dotnet\",\n                Args = new List<string> { @\"C:\\Tools\\MyTool\\MyTool.dll\" },\n                WorkingDirectory = @\"C:\\Tools\\MyTool\",\n                Tools = new List<string> { \"*\" },\n            }\n        };\n    }\n}\n```\n\n<!-- /docs-validate: hidden -->\n\n```csharp\n// Correct configuration for .NET exe\n[\"my-dotnet-server\"] = new McpStdioServerConfig\n{\n    Command = @\"C:\\Tools\\MyServer\\MyServer.exe\",  // Full path with .exe\n    Args = new List<string>(),\n    WorkingDirectory = @\"C:\\Tools\\MyServer\",  // Set working directory\n    Tools = new List<string> { \"*\" },\n}\n\n// For dotnet tool (DLL)\n[\"my-dotnet-tool\"] = new McpStdioServerConfig\n{\n    Command = \"dotnet\",\n    Args = new List<string> { @\"C:\\Tools\\MyTool\\MyTool.dll\" },\n    WorkingDirectory = @\"C:\\Tools\\MyTool\",\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### Comandos npx\n\n<!-- docs-validate: hidden -->\n\n```csharp\nusing GitHub.Copilot;\n\npublic static class McpNpxConfigExample\n{\n    public static void Main()\n    {\n        var servers = new Dictionary<string, McpServerConfig>\n        {\n            [\"filesystem\"] = new McpStdioServerConfig\n            {\n                Command = \"cmd\",\n                Args = new List<string> { \"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\allowed\\\\path\" },\n                Tools = new List<string> { \"*\" },\n            }\n        };\n    }\n}\n```\n\n<!-- /docs-validate: hidden -->\n\n```csharp\n// Windows needs cmd /c for npx\n[\"filesystem\"] = new McpStdioServerConfig\n{\n    Command = \"cmd\",\n    Args = new List<string> { \"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\allowed\\\\path\" },\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### Problemas de caminho\n\n* Use strings brutas (`@\"C:\\path\"`) ou barras (`\"C:/path\"`)\n* Evite espaços em caminhos quando possível\n* Se forem necessários espaços, certifique-se do uso adequado de aspas\n\n#### Antivírus/firewall\n\nWindows Defender ou outro AV pode bloquear:\n\n* Novos executáveis\n* Processos de comunicação via stdin/stdout\n\n**Solução:** Adicione exclusões para o executável do servidor MCP.\n\n### macOS\n\n#### Bloqueio do gatekeeper\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Caminhos do Homebrew\n\n<!-- docs-validate: hidden -->\n\n```typescript\nimport { MCPStdioServerConfig } from \"@github/copilot-sdk\";\n\nconst mcpServers: Record<string, MCPStdioServerConfig> = {\n  \"my-server\": {\n    command: \"/opt/homebrew/bin/node\",\n    args: [\"/path/to/server.js\"],\n    tools: [\"*\"],\n  },\n};\n```\n\n<!-- /docs-validate: hidden -->\n\n```typescript\n// GUI apps may not have /opt/homebrew in PATH\nmcpServers: {\n  \"my-server\": {\n    command: \"/opt/homebrew/bin/node\",  // Full path\n    args: [\"/path/to/server.js\"],\n  },\n}\n```\n\n### Linux\n\n#### Problemas de permissão\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### Bibliotecas compartilhadas ausentes\n\n```bash\n# Check dependencies\nldd /path/to/mcp-server\n\n# Install missing libraries\napt install libfoo  # Debian/Ubuntu\nyum install libfoo  # RHEL/CentOS\n```\n\n## Depuração avançada\n\n### Capturar todo o tráfego MCP\n\nCrie um script wrapper para registrar em log toda a comunicação:\n\n```bash\n#!/bin/bash\n# mcp-debug-wrapper.sh\n\nLOG=\"./mcp-debug-$(date +%s).log\"\nACTUAL_SERVER=\"$1\"\nshift\n\necho \"=== MCP Debug Session ===\" >> \"$LOG\"\necho \"Server: $ACTUAL_SERVER\" >> \"$LOG\"\necho \"Args: $@\" >> \"$LOG\"\necho \"=========================\" >> \"$LOG\"\n\n# Tee stdin/stdout to log file\ntee -a \"$LOG\" | \"$ACTUAL_SERVER\" \"$@\" 2>> \"$LOG\" | tee -a \"$LOG\"\n```\n\nUse-o:\n\n```typescript\nmcpServers: {\n  \"debug-server\": {\n    command: \"/path/to/mcp-debug-wrapper.sh\",\n    args: [\"/actual/server/path\", \"arg1\", \"arg2\"],\n  },\n}\n```\n\n### Inspecionar com o inspetor MCP\n\nUse a ferramenta oficial do MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nIsso fornece uma interface web para:\n\n* Enviar solicitações de teste\n* Exibir respostas\n* Inspecionar esquemas de ferramentas\n\n### Incompatibilidades de versão do protocolo\n\nVerifique se o servidor dá suporte à versão de protocolo que o SDK usa:\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nSe as versões não corresponderem, atualize a biblioteca do servidor MCP.\n\n## Lista de verificação de depuração\n\nAo abrir um problema ou pedir ajuda, colete:\n\n* [ ] Linguagem e versão do SDK\n* [ ] Versão da CLI (`copilot --version`)\n* [ ] Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust etc.)\n* [ ] Configuração completa do servidor MCP (ocultar segredos)\n* [ ] Resultado do teste manual `initialize`\n* [ ] Resultado do teste manual `tools/list`\n* [ ] Logs de depuração do SDK\n* [ ] Qualquer mensagem de erro\n\n## Consulte também\n\n* [Using MCP servers with the GitHub Copilot SDK](/pt/copilot/how-tos/copilot-sdk/features/mcp) - Configuração e instalação\n* [Guia de depuração](/pt/copilot/how-tos/copilot-sdk/troubleshooting/debugging) – Depuração em todo o SDK\n* [Especificação do MCP](https://modelcontextprotocol.io/) – documentos de protocolo oficiais"}