{"meta":{"title":"Guía de depuración del servidor MCP","intro":"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.","product":"GitHub Copilot","breadcrumbs":[{"href":"/es/copilot","title":"GitHub Copilot"},{"href":"/es/copilot/how-tos","title":"Procedimientos"},{"href":"/es/copilot/how-tos/copilot-sdk","title":"SDK de Copilot"},{"href":"/es/copilot/how-tos/copilot-sdk/troubleshooting","title":"Solución de problemas"},{"href":"/es/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"Depuración de MCP"}],"documentType":"article"},"body":"# Guía de depuración del servidor MCP\n\nEsta guía abarca técnicas de depuración específicas de los servidores MCP (Model Context Protocol) cuando se utiliza el SDK de Copilot.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Tabla de contenido\n\n* [Diagnóstico rápido](#quick-diagnostics)\n* [Probar servidores MCP de forma independiente](#testing-mcp-servers-independently)\n* [Problemas comunes](#common-issues)\n* [Problemas específicos de la plataforma](#platform-specific-issues)\n* [Depuración avanzada](#advanced-debugging)\n\n## Diagnóstico rápido\n\n### Checklist\n\nAntes de profundizar, compruebe estos aspectos básicos:\n\n* [ ] El ejecutable del servidor MCP existe y se puede ejecutar.\n* [ ] La ruta de acceso del comando es correcta (use rutas de acceso absolutas cuando tenga dudas)\n* [ ] Las herramientas están habilitadas (`tools: [\"*\"]` o nombres de herramientas específicos)\n* [ ] El servidor implementa correctamente el protocolo MCP (responde a `initialize`)\n* [ ] No hay firewall o antivirus que bloquee el proceso (Windows)\n\n### Habilite el registro de depuración MCP\n\nAgregue variables de entorno a la configuración del 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## Prueba de servidores MCP de forma independiente\n\nPruebe siempre el servidor MCP fuera del SDK en primer lugar.\n\n### Prueba manual del protocolo\n\nEnvíe una `initialize` solicitud a través 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**Respuesta 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 herramientas de prueba\n\nDespués de la inicialización, solicite la lista de herramientas:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**Respuesta esperada:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### Script de prueba interactiva\n\nCree un script de prueba para depurar interactivamente el 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 comunes\n\n### El servidor no se inicia\n\n**Síntomas:** No aparece ninguna herramienta, no hay errores en los registros.\n\n**Causas y soluciones:**\n\n| Causa                               | Solución                                                    |\n| ----------------------------------- | ----------------------------------------------------------- |\n| Ruta de comando incorrecta          | Utilice la ruta de acceso absoluta: `/usr/local/bin/server` |\n| Falta el permiso ejecutable         | Ejecute `chmod +x /path/to/server`:                         |\n| Dependencias faltantes              | Comprobación con `ldd` (Linux) o ejecución manual           |\n| Problemas del directorio de trabajo | Establecer `cwd` en la configuración                        |\n\n**Para depurar, ejecute 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### El servidor se inicia, pero las herramientas no aparecen\n\n**Síntomas:** El proceso de servidor se ejecuta, pero no hay herramientas disponibles.\n\n**Causas y soluciones:**\n\n1. **Herramientas no habilitadas en la configuración:**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **El servidor no expone herramientas:**\n   * Prueba manualmente con la solicitud `tools/list`\n   * Comprobar que el servidor implementa el método `tools/list`\n\n3. **Error en el protocolo de enlace de inicialización:**\n   * El servidor debe responder correctamente a `initialize`\n   * El servidor debe gestionar `notifications/initialized`\n\n### Herramientas enumeradas pero nunca llamadas\n\n**Síntomas:** Las herramientas aparecen en los registros de depuración, pero el modelo no los usa.\n\n**Causas y soluciones:**\n\n1. **Prompt no necesita claramente la herramienta:**\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. **Descripción de la herramienta no 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 herramientas:**\n   * Asegúrese de que `inputSchema` es un esquema JSON válido\n   * Los campos obligatorios deben estar en el array `required`\n\n### Errores de tiempo de espera\n\n**Síntomas:**`MCP tool call timed out` errores.\n\n**Soluciones**:\n\n1. **Aumento del tiempo de espera:**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **Optimizar el rendimiento del servidor:**\n   * Agregar el registro del progreso para identificar el cuello de botella\n   * Tener en cuenta las operaciones asíncronas\n   * Compruebe si hay operaciones de E/S que bloquean el sistema\n\n3. **Para herramientas de ejecución prolongada**, considere transmitir respuestas en streaming si es compatible.\n\n### errores de JSON-RPC\n\n**Síntomas:** Errores de análisis, errores de solicitud no válidos.\n\n**Causas comunes:**\n\n1. **El servidor escribe en stdout incorrectamente:**\n   * Salida de depuración dirigida a stdout en lugar de stderr\n   * Nuevas líneas adicionales o espacios en blanco\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 codificación:**\n   * Asegurar la codificación UTF-8\n   * Sin BOM (marca de orden de bytes)\n\n3. **Trama de mensajes:**\n   * Cada mensaje debe ser un objeto JSON completo.\n   * Delimitado por nueva línea (un mensaje por línea)\n\n## Problemas específicos de la plataforma\n\n### Windows\n\n#### aplicaciones o herramientas de consola de .NET\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```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 ruta\n\n* Usar cadenas sin formato (`@\"C:\\path\"`) o barras diagonales (`\"C:/path\"`)\n* Evitar espacios en rutas siempre que sea posible\n* Si se requieren espacios, asegúrese de que las comillas sean adecuadas\n\n#### Antivirus o firewall\n\nWindows Defender u otro antivirus pueden bloquear:\n\n* Nuevos ejecutables\n* Procesos que se comunican a través de stdin/stdout\n\n**Solución:** Agregue exclusiones para el ejecutable del servidor MCP.\n\n### macOS\n\n#### Bloqueo del controlador de acceso\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Rutas de acceso de Homebrew\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 permisos\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### Faltan bibliotecas compartidas\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## Depuración avanzada\n\n### Captura todo el tráfico MCP\n\nCree un script contenedor para registrar toda la comunicación:\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\nUsa esto:\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### Inspección con el inspector de MCP\n\nUse la herramienta oficial MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nEsto proporciona una interfaz de usuario web para:\n\n* Envío de solicitudes de prueba\n* Ver respuestas\n* Inspección de esquemas de herramientas\n\n### Errores de coincidencia de versiones del protocolo\n\nCompruebe que el servidor admite la versión del protocolo que usa el SDK:\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nSi las versiones no coinciden, actualice la biblioteca del servidor MCP.\n\n## Lista de comprobación de depuración\n\nAl abrir un problema o pedir ayuda, recopile:\n\n* [ ] Lenguaje y versión del SDK\n* [ ] Versión de la CLI (`copilot --version`)\n* [ ] Tipo de servidor MCP (Node.js, Python, .NET, Go, Rust, etc.)\n* [ ] Configuración completa del servidor MCP (ocultar secretos)\n* [ ] Resultado de la prueba manual `initialize`\n* [ ] Resultado de la prueba manual `tools/list`\n* [ ] Depurar registros del SDK\n* [ ] Cualquier mensaje de error\n\n## Consulte también\n\n* [Uso de servidores MCP con el SDK de GitHub Copilot](/es/copilot/how-tos/copilot-sdk/features/mcp) - Configuración y puesta en marcha\n* [Guía de depuración](/es/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - depuración de todo el SDK\n* [Especificación de MCP](https://modelcontextprotocol.io/) : documentos de protocolo oficiales"}