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, bestimmen Sie die Ursache nicht allein anhand des Status: Prüfen Sie Verbindungsart und Fehlerdetails gemeinsam. Dieser Artikel führt durch lokalen Start, entfernte Kommunikation und Authentifizierung, Konfiguration und Freigabe.

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, prüfen Sie die Verbindungsprotokolle mit claude --debug=mcp. Ändern Sie nur die vom tatsächlichen Fehler betroffene Einstellung und prüfen Sie das Ergebnis durch erneutes Verbinden.

1. Was dieser Fehler bedeutet

Beispielsweise kann folgende Meldung im Protokoll erscheinen. Schließen Sie daraus nicht allein auf einen fehlgeschlagenen Serverstart; prüfen Sie auch die vorherigen Protokolleinträge.

MCP error -32000: Connection closed

MCP error -32000: Connection closed zeigt an, dass die Verbindung geschlossen wurde. Das TypeScript-SDK von MCP ordnet -32000 dem Fehler ConnectionClosed zu. Die vorherigen Protokolle zeigen, was die Verbindung beendet hat, etwa ein Serverende oder ein Kommunikationsabbruch. Die Meldung allein unterscheidet nicht zwischen einem Prozessende vor der Initialisierung und einem späteren Verbindungsabbruch. Siehe die Behandlung geschlossener Verbindungen im SDK.

Auch Fehler außerhalb Ihrer Konfiguration kommen infrage. Beispielsweise enthält Issue #20713 den Bericht eines Nutzers über einen Abbruch während der Initialisierung mit Claude Code 2.1.19 unter macOS. Behandeln Sie die Ursachenvermutung eines Nutzers nicht als von Anthropic bestätigte Ursache oder als aktuellen Fehler in sämtlichen Umgebungen. Geben Sie bei einer 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) prüfen Sie fehlende Befehle oder Variablen, beendete Serverprozesse und Protokolle in stdout. Bei entfernten Servern (HTTP) prüfen Sie falsche URLs, Netzwerkprobleme, 5xx-Antworten, Zeitüberschreitungen und Authentifizierung. Ort, Syntax und Geltungsbereich der Konfiguration sind bei beiden relevant. Behaupten Sie ohne Häufigkeitsbelege nicht, es liege „fast immer an der Authentifizierung“ oder „fast immer am Pfad“.

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 allein unterscheidet nicht zwischen lokalem Startproblem und entfernter Kommunikationsstörung. Lesen Sie HTTP-Code oder Fehlertext unter Issue: in claude mcp get <name> beziehungsweise die Details in /mcp. Auch ein beim Verbindungsaufbau mit 401/403 abgelehnter fester Authorization-Header führt zu failed. Außerdem sind null Werkzeuge bei einem Server, der nur Ressourcen oder Prompts anbietet, nicht zwangsläufig ein Fehler. Prüfen Sie zuerst, ob er Werkzeuge bereitstellen soll. 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; beachten Sie die offiziellen Expansionsregeln. Interaktive Sitzungen verlangen eine Freigabe für Projektserver. claude -p und das SDK laden sie dagegen normalerweise ohne diese Abfrage. Ablehnungseinstellungen und weitere Bedingungen erläutert die offizielle Dokumentation zum Projektbereich. Dazu passen auch MCP-Grundlagen und A2A.

4. Den npx-Start unter Windows prüfen

Meldet Windows spawn npx ENOENT, prüfen Sie zuerst Programmdatei und PATH mit where.exe npx. Prüfen Sie auch, ob Node/npm funktioniert und das angegebene Paket startet. Die offizielle Node-Dokumentation erklärt, dass .cmd-Dateien nicht direkt ausführbar sind, und zeigt den Start über eine Shell oder cmd.exe. Das bedeutet jedoch nicht, dass die direkte Angabe von npx in jeder Claude-Code-Umgebung scheitert.

{
  "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: Bestätigen Sie, dass der Server eigenständig läuft, bevor Sie Claude Code die Schuld geben.

Hinweis: Zu viele MCP-Server lassen Werkzeugdefinitionen Kontext verbrauchen, besonders beim ständigen Vorladen. Claude Code lädt Definitionen standardmäßig über die Werkzeugsuche nach, was die Belastung verringert. Dennoch sollten Sie ungenutzte Server deaktivieren. Zu viel Kontext kann sogar Prompt is too long auslösen.

6. Checkliste zur Vorbeugung

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

(1) Tatsächliche Pfade von stdio-Programmen und Skripten prüfen. (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 verweist auf Authentifizierungsprüfungen, pending approval auf die Freigabe eines Projektservers.

Gehen Sie so vor: Status und Issue: lesen → passende Verbindungsprotokolle prüfen → eigenständigen Betrieb beziehungsweise Kommunikation testen → neu verbinden und Operation prüfen. 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.

FAQ

F. /mcp zeigt failed. Wo fange ich an?
A. Verbindungsart und Issue: prüfen. Bei stdio Befehl, Pfad, Umgebungsvariablen und stderr untersuchen; bei HTTP URL, Netzwerk, Serverantwort und Authentifizierung. Auch ein beim Verbindungsaufbau mit 401/403 abgelehnter fester Authorization-Header erzeugt failed. Gehen Sie daher nicht automatisch von einem lokalen Startproblem aus.

Q. Es zeigt „needs authentication“ und die Werkzeuge funktionieren nicht.
A. Das ist ein Remote-Server (HTTP), der eine Authentifizierung verlangt (401/403). Öffnen Sie /mcp und führen Sie die Authentifizierung für diesen Server aus; es geht zur OAuth-Genehmigung im Browser über. Danach werden Tokens sicher gespeichert und automatisch erneuert. Beachten Sie, dass einige Dienste (Microsoft 365, Gmail, Google Calendar) keine lokale Authentifizierung aus Claude Code unterstützen und stattdessen über Settings → Connectors auf claude.ai verbunden werden müssen.

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, können Sie cmd.exe /c npx ... verwenden. Auch WSL braucht eine funktionierende Linux-Umgebung. Ein Betriebssystemwechsel allein garantiert keine Lösung.

F. Der Server ist connected, zeigt aber 0 Werkzeuge.
A. Prüfen Sie, ob der Server überhaupt Werkzeuge bereitstellen soll. Bei reinen Ressourcen oder Prompts sind null Werkzeuge nicht zwangsläufig ein Fehler. Werden Werkzeuge erwartet, prüfen Sie 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 bleibt beim Laden wörtlicher Text; das kann Start oder Authentifizierung scheitern lassen. Geben Sie bei HTTP-Konfigurationen auch type an. Erneute Freigabe allein behebt weder Ablehnungseinstellungen noch Verwaltungsrichtlinien.

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