Guía de depuración del servidor MCP

Esta guía abarca técnicas de depuración específicas de los servidores MCP (Model Context Protocol) cuando se utiliza el SDK de Copilot.

En este artículo

Tabla de contenido

Diagnóstico rápido

Checklist

Antes de profundizar, compruebe estos aspectos básicos:

  • El ejecutable del servidor MCP existe y se puede ejecutar.
  • La ruta de acceso del comando es correcta (use rutas de acceso absolutas cuando tenga dudas)
  • Las herramientas están habilitadas (tools: ["*"] o nombres de herramientas específicos)
  • El servidor implementa correctamente el protocolo MCP (responde a initialize)
  • No hay firewall o antivirus que bloquee el proceso (Windows)

Habilite el registro de depuración MCP

Agregue variables de entorno a la configuración del 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
    },
  },
}

Prueba de servidores MCP de forma independiente

Pruebe siempre el servidor MCP fuera del SDK en primer lugar.

Prueba manual del protocolo

Envíe una initialize solicitud a través 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

Respuesta esperada:

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

Lista de herramientas de prueba

Después de la inicialización, solicite la lista de herramientas:

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

Respuesta esperada:

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

Script de prueba interactiva

Cree un script de prueba para depurar interactivamente el 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 comunes

El servidor no se inicia

Síntomas: No aparece ninguna herramienta, no hay errores en los registros.

Causas y soluciones:

CausaSolución
Ruta de comando incorrectaUtilice la ruta de acceso absoluta: /usr/local/bin/server
Falta el permiso ejecutableEjecute chmod +x /path/to/server:
Dependencias faltantesComprobación con ldd (Linux) o ejecución manual
Problemas del directorio de trabajoEstablecer cwd en la configuración

Para depurar, ejecute manualmente:

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

El servidor se inicia, pero las herramientas no aparecen

Síntomas: El proceso de servidor se ejecuta, pero no hay herramientas disponibles.

Causas y soluciones:

  1. Herramientas no habilitadas en la configuración:

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

  2. El servidor no expone herramientas:

    • Prueba manualmente con la solicitud tools/list
    • Comprobar que el servidor implementa el método tools/list
  3.           **Error en el protocolo de enlace de inicialización:**
    • El servidor debe responder correctamente a initialize
    • El servidor debe gestionar notifications/initialized

Herramientas enumeradas pero nunca llamadas

Síntomas: Las herramientas aparecen en los registros de depuración, pero el modelo no los usa.

Causas y soluciones:

  1.           **Prompt no necesita claramente la herramienta:**

    // 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. Descripción de la herramienta no 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 herramientas:

    • Asegúrese de que inputSchema es un esquema JSON válido
    • Los campos obligatorios deben estar en el array required

Errores de tiempo de espera

Síntomas:MCP tool call timed out errores.

Soluciones:

  1. Aumento del tiempo de espera:

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

  2. Optimizar el rendimiento del servidor:

    • Agregar el registro del progreso para identificar el cuello de botella
    • Tener en cuenta las operaciones asíncronas
    • Compruebe si hay operaciones de E/S que bloquean el sistema

  3. Para herramientas de ejecución prolongada, considere transmitir respuestas en streaming si es compatible.

errores de JSON-RPC

Síntomas: Errores de análisis, errores de solicitud no válidos.

Causas comunes:

  1. El servidor escribe en stdout incorrectamente:

    • Salida de depuración dirigida a stdout en lugar de stderr
    • Nuevas líneas adicionales o espacios en blanco
    // Wrong - pollutes stdout
console.log("Debug info");

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

  2. Problemas de codificación:

    • Asegurar la codificación UTF-8
    • Sin BOM (marca de orden de bytes)

  3. Trama de mensajes:

    • Cada mensaje debe ser un objeto JSON completo.
    • Delimitado por nueva línea (un mensaje por línea)

Problemas específicos de la plataforma

Windows

aplicaciones o herramientas de consola de .NET

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 ruta

  • Usar cadenas sin formato (@"C:\path") o barras diagonales ("C:/path")
  • Evitar espacios en rutas siempre que sea posible
  • Si se requieren espacios, asegúrese de que las comillas sean adecuadas

Antivirus o firewall

Windows Defender u otro antivirus pueden bloquear:

  • Nuevos ejecutables
  • Procesos que se comunican a través de stdin/stdout

Solución: Agregue exclusiones para el ejecutable del servidor MCP.

macOS

Bloqueo del controlador de acceso

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

Rutas de acceso de 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 permisos

chmod +x /path/to/mcp-server

Faltan bibliotecas compartidas

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

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

Depuración avanzada

Captura todo el tráfico MCP

Cree un script contenedor para registrar toda la comunicación:

#!/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"

Usa esto:

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

Inspección con el inspector de MCP

Use la herramienta oficial MCP Inspector:

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

Esto proporciona una interfaz de usuario web para:

  • Envío de solicitudes de prueba
  • Ver respuestas
  • Inspección de esquemas de herramientas

Errores de coincidencia de versiones del protocolo

Compruebe que el servidor admite la versión del protocolo que usa el SDK:

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

Si las versiones no coinciden, actualice la biblioteca del servidor MCP.

Lista de comprobación de depuración

Al abrir un problema o pedir ayuda, recopile:

  • Lenguaje y versión del SDK
  • Versión de la CLI (copilot --version)
  • Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust, etc.)
  • Configuración completa del servidor MCP (ocultar secretos)
  • Resultado de la prueba manual initialize
  • Resultado de la prueba manual tools/list
  • Depurar registros del SDK
  • Cualquier mensaje de error

Consulte también