Guia de depuração do servidor MCP

Sumário

• Diagnóstico Rápido
• Testando servidores MCP de forma independente
• Problemas comuns
• Problemas específicos da plataforma
• Depuração avançada

Diagnóstico rápido

Checklist

Antes de mergulhar fundo, verifique estes conceitos básicos:

• O executável do servidor MCP existe e é executável
• O caminho do comando está correto (use caminhos absolutos quando estiver em dúvida)
• As ferramentas estão habilitadas (tools: ["*"] ou nomes de ferramentas específicos)
• O servidor implementa o protocolo MCP corretamente (responde a initialize)
• Nenhum firewall/antivírus bloqueando o processo (Windows)

Habilitar o registro em log de depuração do MCP

Adicione variáveis de ambiente à configuração do servidor MCP:

mcpServers: {
  "my-server": {
    type: "local",
    command: "/path/to/server",
    args: [],
    env: {
      MCP_DEBUG: "1",
      DEBUG: "*",
      NODE_DEBUG: "mcp",  // For Node.js MCP servers
    },
  },
}

Testar servidores MCP de forma independente

Sempre teste seu servidor MCP fora do SDK primeiro.

Teste de protocolo manual

Enviar uma solicitação initialize por meio de stdin:

# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

# Windows (PowerShell)
'{"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

Resposta esperada:

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

Lista de ferramentas de teste

Após a inicialização, solicite a lista de ferramentas:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

Resposta esperada:

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}

Script de teste interativo

Crie um script de teste para depurar interativamente o servidor MCP:

#!/bin/bash
# test-mcp.sh

SERVER="$1"

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Send initialized notification
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Keep stdin open
cat

Uso:

./test-mcp.sh | /path/to/mcp-server

Problemas comuns

Servidor não iniciado

Sintomas: Nenhuma ferramenta é exibida, nenhum erro nos logs.

Causas & Soluções:

Cause	Solução
Caminho de comando incorreto	Use o caminho absoluto: /usr/local/bin/server
Falta permissão executável	Execute chmod +x /path/to/server
Dependências ausentes	Verificar com ldd (Linux) ou executar manualmente
Problemas no diretório de trabalho	Definir cwd em configuração

Depurar executando manualmente:

# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

O servidor é iniciado, mas as ferramentas não aparecem

Sintomas: O processo do servidor é executado, mas nenhuma ferramenta está disponível.

Causas & Soluções:

1. Ferramentas não habilitadas na configuração:

   mcpServers: {
     "server": {
       // ...
       tools: ["*"],  // Must be "*" or list of tool names
     },
   }
   

2. O servidor não expõe ferramentas:

   • Teste manualmente com a requisição tools/list
   • Verificar se o servidor implementa o método tools/list

3. Falha no handshake de inicialização:

   • O servidor deve responder a initialize corretamente
   • O servidor deve manipular notifications/initialized

Ferramentas listadas, mas nunca chamadas

Sintomas: As ferramentas aparecem em logs de depuração, mas o modelo não as usa.

Causas & Soluções:

1.           **O prompt não precisa claramente da ferramenta:**
   

   // Too vague
   await session.sendAndWait({ prompt: "What's the weather?" });
   
   // Better - explicitly mentions capability
   await session.sendAndWait({ 
     prompt: "Use the weather tool to get the current temperature in Seattle" 
   });
   

2. Descrição da ferramenta não clara:

   // Bad - model doesn't know when to use it
   { name: "do_thing", description: "Does a thing" }
   
   // Good - clear purpose
   { name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." }
   

3. Problemas de esquema de ferramenta:

   • Garantir inputSchema que o esquema JSON seja válido
   • Os campos necessários devem estar na required matriz

Erros de tempo limite

Sintomas:MCP tool call timed out Erros.

Soluções:

1. Aumentar o tempo limite:

   mcpServers: {
     "slow-server": {
       // ...
       timeout: 300000,  // 5 minutes
     },
   }
   

2. Otimizar o desempenho do servidor:

   • Adicionar registro em log de progresso para identificar gargalo
   • Considere operações assíncronas
   • Verificar se há bloqueio de E/S

3. Para ferramentas de longa execução, considere as respostas de streaming se houver suporte.

JSON-RPC erros

Sintomas: Erros de análise, erros de solicitação inválidos.

Causas comuns:

1. O servidor grava no stdout incorretamente:

   • Saída de depuração sendo enviada para stdout em vez de stderr
   • Linhas adicionais ou espaço em branco

   // Wrong - pollutes stdout
   console.log("Debug info");
   
   // Correct - use stderr for debug
   console.error("Debug info");
   

2. Problemas de codificação:

   • Garantir a codificação UTF-8
   • Sem BOM (Marca de ordem dos bytes)

3. Enquadramento de mensagem:

   • Cada mensagem deve ser um objeto JSON completo
   • Delimitado por nova linha (uma mensagem por linha)

Problemas específicos da plataforma

Windows

.NET aplicativos/ferramentas de console

using GitHub.Copilot;

public static class McpDotnetConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["my-dotnet-server"] = new McpStdioServerConfig
            {
                Command = @"C:\Tools\MyServer\MyServer.exe",
                Args = new List<string>(),
                WorkingDirectory = @"C:\Tools\MyServer",
                Tools = new List<string> { "*" },
            },
            ["my-dotnet-tool"] = new McpStdioServerConfig
            {
                Command = "dotnet",
                Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
                WorkingDirectory = @"C:\Tools\MyTool",
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
    Command = @"C:\Tools\MyServer\MyServer.exe",  // Full path with .exe
    Args = new List<string>(),
    WorkingDirectory = @"C:\Tools\MyServer",  // Set working directory
    Tools = new List<string> { "*" },
}

// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
    Command = "dotnet",
    Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
    WorkingDirectory = @"C:\Tools\MyTool",
    Tools = new List<string> { "*" },
}

Comandos npx

using GitHub.Copilot;

public static class McpNpxConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["filesystem"] = new McpStdioServerConfig
            {
                Command = "cmd",
                Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
    Command = "cmd",
    Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
    Tools = new List<string> { "*" },
}

Problemas de caminho

• Use strings brutas (@"C:\path") ou barras ("C:/path")
• Evite espaços em caminhos quando possível
• Se forem necessários espaços, certifique-se do uso adequado de aspas

Antivírus/firewall

Windows Defender ou outro AV pode bloquear:

• Novos executáveis
• Processos de comunicação via stdin/stdout

Solução: Adicione exclusões para o executável do servidor MCP.

macOS

Bloqueio do gatekeeper

# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server

Caminhos do Homebrew

import { MCPStdioServerConfig } from "@github/copilot-sdk";

const mcpServers: Record<string, MCPStdioServerConfig> = {
  "my-server": {
    command: "/opt/homebrew/bin/node",
    args: ["/path/to/server.js"],
    tools: ["*"],
  },
};

// GUI apps may not have /opt/homebrew in PATH
mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

Problemas de permissão

chmod +x /path/to/mcp-server

Bibliotecas compartilhadas ausentes

# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

Depuração avançada

Capturar todo o tráfego MCP

Crie um script wrapper para registrar em log toda a comunicação:

#!/bin/bash
# mcp-debug-wrapper.sh

LOG="/tmp/mcp-debug-$(date +%s).log"
ACTUAL_SERVER="$1"
shift

echo "=== MCP Debug Session ===" >> "$LOG"
echo "Server: $ACTUAL_SERVER" >> "$LOG"
echo "Args: $@" >> "$LOG"
echo "=========================" >> "$LOG"

# Tee stdin/stdout to log file
tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG"

Use-o:

mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

Inspecionar com o inspetor MCP

Use a ferramenta oficial do MCP Inspector:

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Isso fornece uma interface web para:

• Enviar solicitações de teste
• Exibir respostas
• Inspecionar esquemas de ferramentas

Incompatibilidades de versão do protocolo

Verifique se o servidor dá suporte à versão de protocolo que o SDK usa:

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

Se as versões não corresponderem, atualize a biblioteca do servidor MCP.

Lista de verificação de depuração

Ao abrir um problema ou pedir ajuda, colete:

• Linguagem e versão do SDK
• Versão da CLI (copilot --version)
• Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust etc.)
• Configuração completa do servidor MCP (ocultar segredos)
• Resultado do teste manual initialize
• Resultado do teste manual tools/list
• Logs de depuração do SDK
• Qualquer mensagem de erro

Consulte também

• Using MCP servers with the GitHub Copilot SDK - Configuração e instalação
• Guia de depuração – Depuração em todo o SDK
• Especificação do MCP – documentos de protocolo oficiais