Claude Code: MCP-Server verbindet nicht — Ursachen und Lösungen

Sie haben einen MCP-Server (Model Context Protocol) eingerichtet, aber wenn Sie /mcp öffnen, hängt er in einem Zustand wie diesem fest — kommt Ihnen das bekannt vor?

/mcp

  filesystem      ✓ connected      (12 tools)
  github          ✗ failed
  notion          △ needs authentication
  my-server       ⏸ pending approval

MCP ermöglicht Claude Code den Zugriff auf externe Werkzeuge und Daten. Scheitert eine Verbindung, erscheint im Protokoll unter Umständen die Zeile MCP error -32000: Connection closed. Wenn Sie Status, Verbindungsart und Fehlerdetails zusammen betrachten, lässt sich die Ursache eingrenzen. Dieser Artikel geht der Reihe nach lokalen Start, entfernte Kommunikation und Authentifizierung sowie Konfiguration und Freigabe durch.

Das Wichtigste: (1) Status und Details mit /mcp und claude mcp get <name> lesen. (2) failed kann bei lokalen und entfernten Servern auftreten. Bei stdio prüfen Sie Befehl und Umgebungsvariablen, bei HTTP URL, Netzwerk, Serverantwort und Authentifizierung. (3) Bleibt die Ursache unklar, zeichnen Sie mit claude --debug=mcp die Verbindungsprotokolle auf. Ändern Sie nur die Stelle, die zum tatsächlichen Fehler gehört, und prüfen Sie das Ergebnis durch erneutes Verbinden.

1. Was dieser Fehler bedeutet

Schließt sich die Verbindung, erscheint im Protokoll die folgende Zeile.

MCP error -32000: Connection closed

MCP error -32000: Connection closed zeigt an, dass die MCP-Verbindung geschlossen wurde. Das TypeScript-SDK von MCP ordnet -32000 dem Fehler ConnectionClosed zu und gibt diese Meldung aus, wenn sich die Verbindung schließt (siehe die Behandlung geschlossener Verbindungen im SDK). Die Zeile teilt nur das Ergebnis „geschlossen“ mit; der Grund dafür steht in den vorherigen Protokolleinträgen. Dort unterscheiden Sie, ob der Serverprozess vor der Initialisierung beendet wurde oder die Kommunikation nach dem Verbindungsaufbau abbrach.

Auch bei korrekter Konfiguration kann die Verbindung abbrechen. Issue #20713 ist der Bericht eines Nutzers, bei dem sich die Verbindung mit Claude Code 2.1.19 unter macOS während der Initialisierung schloss. Die Ursache „Race Condition“ ist die Einschätzung des Berichterstatters; das Issue wurde im April 2026 als „not planned“ geschlossen. Geben Sie bei einer eigenen Meldung Betriebssystem, Version, Verbindungsart und von Geheimnissen bereinigte Protokolle an.

MCP-Server nutzen häufig zwei Verbindungsarten. (1) stdio (lokal) — Claude Code startet den Serverbefehl als Unterprozess auf Ihrem Rechner und kommuniziert über Standardein- und -ausgabe. (2) HTTP (entfernt) — die Verbindung zu einem Cloudserver erfolgt über eine URL (das ältere SSE ist veraltet). Was „verbindet nicht“ bedeutet, hängt stark von der Verbindungsart ab.

Bei lokalen Servern (stdio) scheitert es an fehlenden Befehlen oder Variablen, sofort beendeten Serverprozessen oder Protokollausgaben in stdout. Bei entfernten Servern (HTTP) sind falsche URLs, Netzwerkprobleme, 5xx-Antworten, Zeitüberschreitungen und Authentifizierung die Ursachen. Fehler bei Ort, Syntax und Geltungsbereich der Konfigurationsdatei kommen bei beiden Verbindungsarten vor.

Zuerst Status und Fehlerdetails festhalten und klären, ob stdio oder HTTP verwendet wird. Wer mehrere Einstellungen gleichzeitig ändert, kann deren Wirkung kaum zuordnen. Nutzen Sie die folgende Tabelle als Einstieg und untersuchen Sie jeweils eine passende Ursache.

2. Zuerst den Status mit /mcp lesen

Führen Sie in der Sitzung /mcp aus (oder aus der Shell claude mcp list / claude mcp get <name>), um den Zustand jedes Servers zu sehen. Die wichtigsten Status und ihre Bedeutung:

failed erscheint sowohl bei einem lokalen Startfehler als auch bei gescheiterter entfernter Kommunikation. Unterscheiden lassen sich beide anhand der Details: In claude mcp list stehen sie am Ende der Zeile ✘ Failed to connect, in claude mcp get <name> und in der Detailansicht von /mcp in der Zeile Issue: – jeweils HTTP-Status oder Fehlercode und der vom Server zurückgegebene Fehlertext. Auch ein beim Verbindungsaufbau mit 401/403 abgelehnter fester Authorization-Header führt zu failed.

Bricht die Verbindung zu einem entfernten Server während der Sitzung ab, versucht Claude Code automatisch, sie wiederherzustellen; währenddessen zeigt /mcp pending an (hier nicht im Sinne von „Freigabe ausstehend“). Scheitern alle fünf Versuche und wechselt der Server zu failed, erscheint die Meldung MCP server "<name>" disconnected · open /mcp to reconnect (ist eine erneute Authentifizierung nötig, lautet der Status needs authentication). stdio-Server werden nicht automatisch neu verbunden; verbinden Sie sie manuell über /mcp. Außerdem markiert /mcp Server, die Werkzeugfunktionen deklarieren, aber kein einziges Werkzeug bereitstellen. Bei einem Server, der nur Ressourcen oder Prompts anbietet, sind null Werkzeuge normal. Siehe die offiziellen Statusdetails.

3. Hauptursachen für Fehler und ihre Behebung

Diese Punkte helfen bei Verbindungsfehlern und unpassender Konfiguration. Beginnen Sie mit den Punkten für Ihre Verbindungsart.

Eine Projektdatei .mcp.json lässt sich teilen, aber committen Sie keine geheimen Werte direkt. Verweisen Sie beispielsweise auf ${API_KEY} und setzen Sie den Wert in jeder Umgebung. Einige geschützte Variablennamen, darunter Claude Codes eigene Zugangsdaten, werden in entfernten URLs und Headern zu leeren Zeichenfolgen (offizielle Expansionsregeln). Interaktive Sitzungen verlangen eine Freigabe für Projektserver, claude -p und das SDK laden sie dagegen ohne diese Abfrage. Server, die trotzdem nicht geladen werden sollen, tragen Sie in disabledMcpjsonServers ein (offizielle Dokumentation zum Projektbereich). Verwandt: MCP-Grundlagen, A2A.

4. Den npx-Start unter Windows prüfen

Meldet Windows spawn npx ENOENT, sehen Sie zuerst mit where.exe npx nach Programmdatei und PATH. Testen Sie anschließend, ob Node/npm funktioniert und das angegebene Paket eigenständig startet. Laut der offiziellen Node-Dokumentation lassen sich .cmd-Dateien unter Windows nicht direkt ausführen, sondern werden über eine Shell oder cmd.exe gestartet.

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}

5. Der Diagnose-Workflow

Wenn die Ursache unklar ist, gehen Sie von oben nach unten vor. Der Trick: Prüfen Sie, ob der Server eigenständig läuft, bevor Sie Claude Code verdächtigen.

Hinweis: Claude Code lädt Definitionen standardmäßig über die Werkzeugsuche erst bei Bedarf, sodass zusätzliche Server den Kontext kaum belasten. Bei Servern mit alwaysLoad oder Konfigurationen mit deaktivierter Werkzeugsuche werden die Definitionen jedoch von Anfang an geladen; deaktivieren Sie ungenutzte Server daher mit /mcp disable <name>. Zu viel Kontext führt zu Prompt is too long.

6. Checkliste zur Vorbeugung

Gewohnheiten, um bei MCP-Verbindungen nicht hängenzubleiben.

(1) stdio-Programme und Skripte mit ihrem tatsächlichen Pfad angeben. (2) stdio-Variablen von HTTP-Authentifizierungsheadern unterscheiden und Geheimnisse aus geteilten Dateien heraushalten. (3) Unter Windows where.exe npx und Node/npm prüfen; cmd.exe /c nur bei Problemen mit der Startmethode versuchen. (4) .mcp.json im Projektstamm ablegen und JSON-Syntax, Variablen und Freigabe prüfen. (5) stdio-Protokolle nach stderr statt stdout schreiben. (6) Jeweils eine Änderung vornehmen, neu verbinden und die benötigte Operation testen.

Fazit

Untersuchen Sie MCP-Verbindungsfehler in Claude Code anhand von Status, Verbindungsart und Fehlerdetails gemeinsam. failed beschränkt sich nicht auf lokale Startfehler: Auch HTTP-Kommunikationsfehler und abgelehnte feste Authentifizierungsheader können dahinterstehen. needs authentication ist der Einstieg zur Authentifizierung, pending approval zur Überprüfung der Freigabe eines Projektservers.

Gehen Sie so vor: Status und Issue: lesen → passende Verbindungsprotokolle lesen → eigenständigen Betrieb beziehungsweise Kommunikation testen → neu verbinden und Operation ausprobieren. Die Debug-Kategorie wählen Sie mit claude --debug=mcp. Mit --debug-file ./claude-mcp-debug.log speichern Sie die Protokolle. Entfernen Sie Geheimnisse vor dem Teilen. Verwandt: Was ist MCP?, MCP-Server monetarisieren, Claude-Code-Fehler im Überblick.

Ist der Verlauf in der Codex-App noch sichtbar, scheitert aber nur das Senden, liegt kein MCP-Problem vor, sondern eines des Unterhaltungszustands. Das behandelt Codex „thread not found“: Fehlerdiagnose und ein Wiederherstellungsbeispiel.

FAQ

F. /mcp zeigt failed. Wo fange ich an?
A. Verbindungsart und Issue: ansehen. Bei stdio kommen Befehl, Pfad, Umgebungsvariablen und stderr infrage, bei HTTP URL, Netzwerk, Serverantwort und Authentifizierung. Auch ein beim Verbindungsaufbau mit 401/403 abgelehnter fester Authorization-Header führt zu failed; Issue: zeigt dann den HTTP-Status.

F. Es zeigt „needs authentication“ und die Werkzeuge funktionieren nicht.
A. Das Vorgehen hängt von der Authentifizierungsart ab. Bei OAuth-Servern authentifizieren Sie sich über /mcp. Bei einem eigenen headersHelper erscheint dieser Status, wenn ein Werkzeugaufruf 401/403 zurückgibt und auch der erneute Versuch mit neu abgerufenen Zugangsdaten scheitert. Liefert der Helper einen Authorization-Header, wechselt Claude Code nicht zu OAuth. Korrigieren Sie die Quelle und die zurückgegebenen Zugangsdaten und verbinden Sie sich erneut. Von Anthropic bereitgestellte Konnektoren wie Microsoft 365, Gmail und Google Calendar unterstützen kein lokales OAuth aus Claude Code. Fügen Sie sie per claude mcp add oder .mcp.json hinzu und melden sich über /mcp an, erscheint is Anthropic-hosted and doesn't support local OAuth; entfernen Sie dann diese Registrierung und verbinden Sie den Konnektor in den Konnektoreinstellungen von claude.ai. Siehe die offizielle Dokumentation zur eigenen Authentifizierung.

F. Mein npx-Server verbindet sich unter Windows nicht.
A. Prüfen Sie where.exe npx und Node/npm und starten Sie dasselbe Paket mit denselben Argumenten. Liegt es an der Startmethode der .cmd-Datei, starten Sie mit cmd.exe /c npx .... Für WSL stellen Sie Node und Pakete auf der Linux-Seite bereit.

F. Der Server ist connected, zeigt aber 0 Werkzeuge.
A. Prüfen Sie zuerst, ob der Server überhaupt Werkzeuge bereitstellen soll. Bei Servern, die nur Ressourcen oder Prompts anbieten, sind null Werkzeuge normal. Deklariert der Server Werkzeugfunktionen, liefert aber null Werkzeuge, markiert /mcp ihn; prüfen Sie dann angebotene Funktionen, Berechtigungen, Servereinstellungen und Protokolle und verbinden Sie erneut. stdio-Diagnoseprotokolle gehören nach stderr, nicht in den Protokolldatenstrom stdout.

F. Ich habe einen Server konfiguriert, kann ihn aber nicht nutzen.
A. Prüfen Sie, ob die geteilte Projektdatei .mcp.json im Projektstamm liegt, und danach Syntax, Geltungsbereich und Freigabestatus. Eine undefinierte ${VAR} ohne Vorgabewert erzeugt eine Warnung und wird als wörtlicher Text geladen, was zu Start- oder Authentifizierungsfehlern führt. Geben Sie bei HTTP-Konfigurationen auch type an. Liefert claude mcp get <name> den Status ✘ Rejected, steht der Server in einer der Einstellungsdateien unter disabledMcpjsonServers; wiederholen Sie dann nicht nur die Freigabe, sondern entfernen Sie diesen Eintrag.

Referenzen zu Konfiguration und Befehlen: env-Einstellungen, CLI-Referenz, MCP-Verbindungsreferenz.