Depuración de servidores MCP en el SDK de Copilot

Diagnostique y corrija problemas con los servidores MCP integrados con SDK de Copilot, incluidos los errores de inicio del servidor, los problemas de detección de herramientas y los errores de protocolo.

¿Quién puede utilizar esta característica?

SDK de GitHub Copilot está disponible con todos los Copilot planes.

En este artículo

Nota:

          SDK de Copilot actualmente está en versión preliminar pública. La funcionalidad y la disponibilidad están sujetas a cambios.

Diagnóstico rápido

Lista de comprobación

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)
  • Ningún firewall o antivirus está bloqueando el proceso (Windows)

Habilite el registro de depuración MCP

Agregue variables de entorno a la configuración del servidor MCP:

TypeScript
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:

Bash
# 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

          **Respuesta esperada:**

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

Para obtener un ejemplo de Windows PowerShell, consulte Guía de depuración del servidor MCP en el github/copilot-sdk repositorio.

Lista de herramientas de prueba

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

Bash
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:

Bash
#!/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:

Bash
./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.
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:

Bash
# 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.

1. Herramientas no habilitadas en la configuración:

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

  1.        **El servidor no expone herramientas:** Pruebe manualmente con una `tools/list` solicitud. Compruebe que el servidor implementa el `tools/list` método .

  2.           **Error en el protocolo de enlace de inicialización:** El servidor debe responder correctamente y `initialize` controlar `notifications/initialized`.

Herramientas enumeradas pero nunca llamadas

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

  1.           **Prompt no necesita claramente la herramienta:**
    TypeScript
    // 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:**
    TypeScript
    // 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 `inputSchema` que es un esquema JSON válido. Los campos obligatorios deben aparecer en la `required` matriz.

Errores de tiempo de espera

          **Síntomas:**`MCP tool call timed out` errores.

  1. Aumente el tiempo de espera:

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

  2. Optimice el rendimiento del servidor añadiendo el registro de progreso para identificar el cuello de botella, teniendo en cuenta las operaciones asincrónicas y comprobar la E/S bloqueante.

  3. En el caso de las herramientas de larga duración, considere transmitir las respuestas si esta capacidad 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 que va a stdout en lugar de stderr, o nuevas líneas adicionales o espacios en blanco:
    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

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

  2.        **Problemas de codificación:** Asegúrese de 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

En Windows, el antivirus o el software de firewall pueden bloquear nuevos ejecutables o procesos que se comunican a través de stdin/stdout. Agregue exclusiones para el ejecutable del servidor MCP si es necesario.

Para ver ejemplos de configuración específicos de Windows para aplicaciones de consola de .NET y comandos NPX, consulte Guía de depuración del servidor MCP en el repositorio github/copilot-sdk.

          **Problemas de ruta de acceso:**
  • Use cadenas de texto sin procesar (@"C:\path") o barras diagonales ("C:/path").
  • Evite espacios en rutas de acceso siempre que sea posible.
  • Si se requieren espacios, asegúrese de que las comillas sean adecuadas.

macOS

  1.        **Bloqueo de gatekeeper:** Si el servidor está bloqueado:
    Bash
    xattr -d com.apple.quarantine /path/to/mcp-server

  2.        **Rutas de acceso de Homebrew:** Es posible que las aplicaciones de GUI no tengan `/opt/homebrew` en PATH. Use la ruta de acceso completa:
    TypeScript
    mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

  1.        **Problemas de permisos:**
    Bash
    chmod +x /path/to/mcp-server

  2.        **Faltan bibliotecas compartidas:**
    Bash
    # 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:

Bash
#!/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:

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

Inspeccionar con el inspector de MCP

Use la herramienta oficial MCP Inspector:

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

Esto proporciona una interfaz de usuario web para enviar solicitudes de prueba, ver respuestas e inspeccionar 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 solicitar ayuda en Problemas de GitHub, recopile:

  • Lenguaje y versión del SDK
  • Versión de la CLI (copilot --version)
  • Tipo de servidor MCP (Node.js, Python, .NET, Go, 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