Guia de depuração do servidor MCP

Este guia aborda técnicas de depuração específicas para servidores MCP (Protocolo de Contexto de Modelo) ao usar o SDK do Copilot.

Neste artigo

Sumário

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:

CauseSolução
Caminho de comando incorretoUse o caminho absoluto: /usr/local/bin/server
Falta permissão executávelExecute chmod +x /path/to/server
Dependências ausentesVerificar com ldd (Linux) ou executar manualmente
Problemas de diretório de trabalhoDefinir 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

  • Usar cadeias de caracteres brutas (@"C:\path") ou barras ("C:/path")
  • Evite espaços em caminhos quando possível
  • Se forem necessários espaços, certifique-se de usar aspas corretamente

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