MCP-Debugging-Checkliste: 80 % der Probleme in 10 Minuten beheben
Kurze Checkliste zur Fehlersuche bei häufigen MCP-Problemen. Sie umfasst Konfigurationsprüfung, Neustart-Anforderungen, Auth-Header, Tool-Liste und minimale Testaufrufe – mit Links zu detaillierten Fehlerbehebungsanleitungen.
⚡ Schnellfix-Checkliste
Diese Punkte der Reihe nach durchgehen. Die meisten Probleme sind in den ersten 5 Schritten behoben.
Schritt 1: Konfigurationsdatei prüfen
Konfigurationsprüfung
- Konfigurationsdatei liegt am richtigen Ort
- JSON-Syntax ist gültig (keine nachgestellten Kommas, korrekte Anführungszeichen)
- Servername entspricht dem erwarteten Format
- URL-Endpoint ist korrekt:
https://mcp.corcava.com - Konfigurationsstruktur entspricht den Client-Anforderungen
Schritt 2: Authorization-Header prüfen
Auth-Header-Prüfung
- Authorization-Header in der Konfiguration vorhanden
- Format ist korrekt:
"Bearer YOUR_API_KEY" - Leerzeichen nach „Bearer“ (erforderlich)
- API-Key ist aktiv und nicht widerrufen
- Kein zusätzliches Leerzeichen oder Sonderzeichen im Key
Schritt 3: Client neu starten
Neustart-Anforderungen
- Client vollständig beendet (nicht nur Fenster geschlossen)
- Client nach Konfigurationsänderungen neu gestartet
- Konfigurationsdatei vor Neustart gespeichert
- Keine Config-Änderungen während der Laufzeit des Clients
Schritt 4: Tool-Liste prüfen
Tool-Verfügbarkeit
- MCP-Server erscheint in der Liste verfügbarer Server
- Tool-Liste ist nicht leer
- Erwartete Tools sichtbar (list_tasks, create_task usw.)
- Keine Verbindungsfehler in den Client-Logs
Schritt 5: Mit minimalem Aufruf testen
Minimaler Test
- Mit Nur-Lesen-Aufruf testen: „Liste meine Corcava-Projekte“
- Operation schließt ohne Fehler ab
- Antwortzeit angemessen (<5 Sekunden)
- Zurückgegebene Daten sind korrekt
Schritt 6: Netzwerk und Verbindung prüfen
Netzwerkprüfung
- Endpoint erreichbar:
https://mcp.corcava.com - Keine Firewall blockiert MCP-Verbindungen
- Firmen-Proxy bei Bedarf konfiguriert
- DNS-Auflösung funktioniert
Schritt 7: Berechtigungen prüfen
Berechtigungsprüfung
- API-Key hat nötige Berechtigungen für die Operation
- Key hat Zugriff auf den richtigen Workspace
- Keine 403-Forbidden-Fehler bei Tool-Aufrufen
- Schreibrechte geprüft, falls Schreibzugriffe nötig
Schnelle Diagnose-Befehle
Test-Prompts
Mit diesen Prompts Ihr Setup testen:
"Liste meine Corcava-Projekte"
"Liste verfügbare MCP-Tools von Corcava"
"Details zur Aufgabe [Task-ID] von Corcava abrufen"
Wenn das funktioniert, ist die Grundkonfiguration in Ordnung. Sonst die Checkliste oben durchgehen.
Häufige Probleme und schnelle Lösungen
Problem: Tools erscheinen nicht
Schnelle Lösung:
- Config-JSON prüfen
- Auth-Header-Format prüfen
- Client vollständig neu starten
Problem: 401 Nicht autorisiert
Schnelle Lösung:
- Prüfen, ob API-Key aktiv ist
- „Bearer “-Format prüfen (Leerzeichen nötig)
- Key bei Bedarf neu erzeugen
Problem: Verbindung fehlgeschlagen
Schnelle Lösung:
- Endpoint-Erreichbarkeit testen
- Firewall-/Proxy-Einstellungen prüfen
- DNS-Auflösung prüfen
Weitere Ressourcen
Fehlerbehebungs-Index
Vollständige Fehlerbehebungsanleitung
Erste MCP-Session
Smoke-Test-Skript
Config Generator
Korrekte Konfiguration erzeugen
Config-JSON-Fehler
Konfigurationssyntax korrigieren
Fix MCP Issues Quickly
Mit dieser Checkliste die meisten MCP-Probleme in Minuten lösen