{"meta":{"title":"MCP-Serverdebugginghandbuch","intro":"In diesem Handbuch werden Debuggingtechniken behandelt, die für MCP-Server (Model Context Protocol) bei Verwendung des Copilot SDK spezifisch sind.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/copilot","title":"GitHub Copilot"},{"href":"/de/copilot/how-tos","title":"Vorgehensweisen"},{"href":"/de/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/de/copilot/how-tos/copilot-sdk/troubleshooting","title":"Problembehandlung"},{"href":"/de/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"MCP-Debugging"}],"documentType":"article"},"body":"# MCP-Serverdebugginghandbuch\n\nIn diesem Handbuch werden Debuggingtechniken behandelt, die für MCP-Server (Model Context Protocol) bei Verwendung des Copilot SDK spezifisch sind.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Inhaltsverzeichnis\n\n* [Schnelldiagnose](#quick-diagnostics)\n* [Unabhängiges Testen von MCP-Servern](#testing-mcp-servers-independently)\n* [Häufige Probleme](#common-issues)\n* [Plattformspezifische Probleme](#platform-specific-issues)\n* [Erweitertes Debuggen](#advanced-debugging)\n\n## Schnelle Diagnose\n\n### Checklist\n\nBevor Sie tief tauchen, überprüfen Sie diese Grundlagen:\n\n* [ ] Die ausführbare Datei des MCP-Servers ist vorhanden und kann ausgeführt werden.\n* [ ] Befehlspfad ist richtig (verwenden Sie absolute Pfade, wenn sie zweifelsfrei sind)\n* [ ] Tools sind aktiviert (`tools: [\"*\"]` oder bestimmte Toolnamen)\n* [ ] Server implementiert das MCP-Protokoll korrekt (antwortet auf `initialize`)\n* [ ] Kein Firewall/Antivirus blockiert den Prozess (Windows)\n\n### Aktivieren der MCP-Debugprotokollierung\n\nHinzufügen von Umgebungsvariablen zur MCP-Serverkonfiguration:\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## Unabhängiges Testen von MCP-Servern\n\nTesten Sie ihren MCP-Server immer außerhalb des SDK zuerst.\n\n### Manueller Protokolltest\n\nSenden Sie eine `initialize` Anfrage über „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**Erwartete Antwort:**\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### Liste der Test-Tools\n\nFordern Sie nach der Initialisierung die Toolsliste an:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**Erwartete Antwort:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### Interaktives Testskript\n\nErstellen Sie ein Testskript, um Ihren MCP-Server interaktiv zu debuggen:\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\nVerwendung:\n\n```bash\n./test-mcp.sh | /path/to/mcp-server\n```\n\n## Häufig auftretende Probleme\n\n### Server wird nicht gestartet\n\n**Symptome:** Es werden keine Tools angezeigt, keine Fehler in Protokollen.\n\n**Ursachen & Lösungen:**\n\n| Ursache                              | Lösung                                              |\n| ------------------------------------ | --------------------------------------------------- |\n| Falscher Befehlspfad                 | Absoluter Pfad verwenden: `/usr/local/bin/server`   |\n| Fehlende Ausführungsberechtigung     | Führen Sie `chmod +x /path/to/server` aus           |\n| Fehlende Abhängigkeiten              | Mit `ldd` überprüfen (Linux) oder manuell ausführen |\n| Arbeitsverzeichnisprobleme           |                                                     |\n| `cwd` in der Konfiguration festlegen |                                                     |\n\n**Debuggen durch manuelles Ausführen:**\n\n```bash\n# Run exactly what the SDK would run\ncd /expected/working/dir\n/path/to/command arg1 arg2\n```\n\n### Der Server startet, aber die Werkzeuge werden nicht angezeigt.\n\n**Symptome:** Der Serverprozess wird ausgeführt, aber es sind keine Tools verfügbar.\n\n**Ursachen & Lösungen:**\n\n1. **In der Konfiguration nicht aktivierte Tools:**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **Der Server macht keine Tools verfügbar:**\n   * Mit `tools/list` Anfrage manuell testen\n   * Prüfen, ob der Server die Methode `tools/list` implementiert\n\n3. **Initialisierungs-Handshake schlägt fehl:**\n   * Der Server muss auf `initialize` korrekt reagieren.\n   * Der Server muss `notifications/initialized` verarbeiten.\n\n### Aufgeführte, aber nie aufgerufene Tools\n\n**Symptome:** Tools werden in Debugprotokollen angezeigt, aber das Modell verwendet sie nicht.\n\n**Ursachen & Lösungen:**\n\n1. **Prompt benötigt das Tool nicht eindeutig:**\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. **Beschreibung des Tools unklar:**\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. **Toolschemaprobleme:**\n   * Sicherstellen, dass es sich um `inputSchema` ein gültiges JSON-Schema handelt\n   * Erforderliche Felder müssen sich im `required` Array befinden.\n\n### Timeoutfehler\n\n**Symptome:**`MCP tool call timed out` Fehler.\n\n**Lösungen :**\n\n1. **Timeout erhöhen:**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **Optimieren der Serverleistung:**\n   * Protokollierung des Fortschritts hinzufügen, um Engpässe zu identifizieren\n   * Berücksichtigen Sie asynchrone Vorgänge\n   * Überprüfen auf Blockieren von E/A\n\n3. **Bei lang andauernden Tools** sollten Sie Streamingantworten in Betracht ziehen, wenn diese unterstützt werden.\n\n### JSON-RPC Fehler\n\n**Symptome:** Analysefehler, ungültige Anforderungsfehler.\n\n**Häufige Ursachen:**\n\n1. **Server schreibt fälschlicherweise in stdout:**\n   * Debug-Ausgabe geht an stdout statt an stderr\n   * Zusätzliche Neulinien oder Leerzeichen\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. **Codierungsprobleme:**\n   * Sicherstellen der UTF-8-Codierung\n   * Kein BOM (Byte Order Mark)\n\n3. **Nachrichtenrahmen:**\n   * Jede Nachricht muss ein vollständiges JSON-Objekt sein.\n   * Zeilentrennzeichen (eine Nachricht pro Zeile)\n\n## Plattformspezifische Probleme\n\n### Windows\n\n#### .NET Konsolen-Apps/-Tools\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#### npx-Befehle\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#### Pfadprobleme\n\n* Verwenden Sie Rohzeichenfolgen (`@\"C:\\path\"`) oder Schrägstriche (`\"C:/path\"`)\n* Vermeiden Sie Leerzeichen in Pfaden, wenn möglich.\n* Wenn Leerzeichen erforderlich sind, stellen Sie sicher, dass sie richtig zitiert werden\n\n#### Antivirus/Firewall\n\nWindows Defender oder ein anderer AV kann Folgendes blockieren:\n\n* Neue ausführbare Dateien\n* Kommunikationsprozesse über stdin/stdout\n\n**Lösung:** Fügen Sie Ausschlüsse für die ausführbare Datei des MCP-Servers hinzu.\n\n### macOS\n\n#### Gatekeeper-Blockierung\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Homebrew-Pfade\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#### Berechtigungsprobleme\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### Fehlende gemeinsame Bibliotheken\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## Erweitertes Debuggen\n\n### Gesamten MCP-Datenverkehr erfassen\n\nErstellen Sie ein Wrapperskript, um die gesamte Kommunikation zu protokollieren:\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\nVerwenden Sie sie:\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### Mit MCP-Inspektor prüfen\n\nVerwenden Sie das offizielle MCP Inspector-Tool:\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nDadurch wird eine Web-UI für Folgendes bereitgestellt:\n\n* Senden von Testanforderungen\n* Antworten anzeigen\n* Tool-Schemata prüfen\n\n### Protokollversionskonflikten\n\nÜberprüfen Sie, ob ihr Server die Protokollversion unterstützt, die das SDK verwendet:\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nWenn versionen nicht übereinstimmen, aktualisieren Sie Ihre MCP-Serverbibliothek.\n\n## Checkliste zum Debuggen\n\nWenn Sie ein Issue öffnen oder um Hilfe bitten, halten Sie Folgendes bereit:\n\n* [ ] SDK-Sprache und -Version\n* [ ] CLI-Version (`copilot --version`)\n* [ ] MCP-Servertyp (Node.js, Python, .NET, Go, Rust und mehr)\n* [ ] Vollständige MCP-Serverkonfiguration (redact secrets)\n* [ ] Ergebnis des manuellen `initialize` Tests\n* [ ] Ergebnis des manuellen `tools/list` Tests\n* [ ] Debugprotokolle aus DEM SDK\n* [ ] Fehlermeldungen\n\n## Siehe auch\n\n* [AUTOTITLE –](/de/copilot/how-tos/copilot-sdk/features/mcp) Konfiguration und Einrichtung\n* [Debughandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/debugging) – SDK-weites Debuggen\n* [MCP-Spezifikation](https://modelcontextprotocol.io/) - Offizielle Protokolldokumente"}