MCP-Verbindungsfehler: stdio, HTTP und Konfiguration
MCP verbindet sich nicht? Startbefehl, JSON, stdio, HTTP-Endpunkt und Anmeldung systematisch prüfen. Mit Fehlertabelle und nachvollziehbarem Ablauf.
Ein MCP-Server erscheint nicht im Client oder verliert die Verbindung. Beginnen Sie bei der ersten fehlgeschlagenen Stufe: Wird die Konfiguration gelesen, startet der Prozess, gelingt die Verbindung und erscheint das benötigte Werkzeug? Diese Reihenfolge verhindert, dass ein Pfadfehler durch Änderungen an Zugangsdaten verdeckt wird. Notieren Sie den genauen Fehler und ändern Sie jeweils nur einen Punkt.
Zuerst den Verbindungsweg bestimmen
Bei stdio startet der Client einen Unterprozess und tauscht Protokollnachrichten über dessen Ein- und Ausgabe aus. Streamable HTTP verbindet den Client mit einem HTTP-Endpunkt eines eigenständigen Serverprozesses. Das ältere HTTP+SSE-Verfahren ist davon zu unterscheiden. Dass eine Adresse im Browser eine Antwort liefert, belegt noch keine erfolgreiche MCP-Verbindung. Prüfen Sie in der Dokumentation, welchen Weg Server und Client tatsächlich unterstützen.
Suchen Sie den Server über Name, Paket oder Repository in der Registersuche. Lesen Sie die deklarierte Verbindung und erstellen Sie bei vorhandener Startvorlage eine passende Clientkonfiguration. Falls mehrere Einträge ähnlich heißen, nutzen Sie den Vergleich. Übertragen Sie keine entfernte URL in ein Feld, das einen lokalen Startbefehl erwartet.
Lokale Startfehler und JSON prüfen
Ein stdio-Prozess braucht die passende Laufzeit und einen in seiner Umgebung erreichbaren Befehl. Desktopprogramme können eine andere Umgebung als Ihr Terminal haben. Prüfen Sie Befehl, Argumentliste, Arbeitsverzeichnis und erforderliche Variablen. Verwenden Sie den tatsächlichen Konfigurationsort des Clients. Eine syntaktisch gültige JSON-Datei am falschen Ort wird nicht dadurch wirksam, dass Sie den Server mehrfach neu starten.
Die Sammelprüfung kann unterstützte JSON-Konfigurationsformen einlesen und Registerbezüge auflösen. Sie führt die Server nicht aus und beweist deshalb keinen erfolgreichen Start. Achten Sie auf die vom Werkzeug ausdrücklich genannten Prüfgrenzen. Bei TOML oder einer anderen Clientform müssen Sie die jeweilige Formatprüfung getrennt behandeln.
| Beobachtung | Mögliche Ursache | Nächster Prüfschritt |
|---|---|---|
| Server erscheint nicht | Datei nicht gelesen oder falsche Struktur | Clientformat und Speicherort prüfen |
| Befehl nicht gefunden | Laufzeit oder Suchpfad fehlt | Startumgebung und Programmpfad prüfen |
| Protokoll nicht lesbar | Unpassende Ausgabe auf stdout | Protokollausgabe von Logs trennen |
| HTTP 401 oder 403 | Anmeldung oder Zugriff abgewiesen | Serverhinweis und Berechtigung lesen |
| HTTP 404 oder 405 | Pfad, Methode oder Sitzung unpassend | Dokumentierten Endpunkt prüfen |
| Werkzeug fehlt | Andere Fassung oder Fähigkeit | Werkzeugliste mit Dokumentation abgleichen |
HTTP-Antworten im Zusammenhang lesen
Die MCP-Transportbeschreibung der Fassung 2025-11-25 erlaubt bei Streamable HTTP unter bestimmten Bedingungen eine Antwort 405 auf GET. Ein Browserabruf allein ist daher kein allgemeiner Funktionstest. Ebenso kann bei einer zuvor aufgebauten Sitzung eine 404 auf eine abgelaufene Sitzungskennung hinweisen. Prüfen Sie die Meldung im Kontext des Clients und der dokumentierten Protokollfassung, statt aus einem Statuscode sofort auf einen ausgefallenen Dienst zu schließen.
Mit einem kleinen Test abschließen
Sichern Sie die bisherige Konfiguration lokal, ohne sie samt Geheimnissen in ein öffentliches Ticket zu kopieren.
Prüfen Sie zuerst Format und Startweg, anschließend Anmeldung und Verbindung. Halten Sie fest, welche Änderung welchen Fehler beseitigt hat.
Lassen Sie die Werkzeugliste im Client anzeigen. Wählen Sie eine begrenzte, für Ihre Testumgebung geeignete Operation.
Vergleichen Sie das Ergebnis mit Ihrer Erwartung und dokumentieren Sie Clientversion, Serverfassung und verbleibende Einschränkungen.
- Ist jede Ausgabe auf stderr ein Fehler?
- Nein. stdio-Server dürfen dort auch normale Diagnosemeldungen ausgeben. Lesen Sie den Inhalt und den Prozessstatus zusammen.
- Dürfen Startmeldungen auf stdout erscheinen?
- Bei stdio gehört dort ausschließlich gültige Protokollausgabe hin. Zusätzliche Textmeldungen können die Kommunikation stören.
- Beweist HTTP 200, dass der Server funktioniert?
- Nein. Prüfen Sie Initialisierung, Werkzeugliste und die tatsächlich benötigte Operation im passenden Client.
- Warum sollte ich nur einen Punkt zugleich ändern?
- So bleibt nachvollziehbar, welche Änderung die beobachtete Stufe repariert hat. Mehrere gleichzeitige Änderungen erschweren die Gegenprüfung.
Quellen geprüft am 1. Oktober 2026. Die Checklisten sind redaktionelle Vorschläge für Ihre eigene Umgebung.
- MCP specification 2025-11-25: transports
Abrufbefehl anzeigen
curl -s https://modelcontextprotocol.io/specification/2025-11-25/basic/transports