Inhaltsverzeichnis
Du hast einen MCP-Server (Model Context Protocol) eingerichtet, aber wenn du /mcp öffnest, hängt er in einem Zustand wie diesem fest — kommt dir das bekannt vor?
/mcp
filesystem ✓ connected (12 tools)
github ✗ failed
notion △ needs authentication
my-server ⏸ pending approvalMCP verleiht Claude Code „Hände" — externe Werkzeuge (Dateioperationen, GitHub, Datenbanken, diverse APIs) —, doch die Verbindungen geraten häufiger ins Stocken, als man erwarten würde. Die Ursachen teilen sich in drei Familien: „Fehler beim Start des lokalen Unterprozesses", „Remote-Authentifizierung" und „Fehler in der Konfigurationsdatei" — und der Status von /mcp verrät dir, welche davon vorliegt. Dieser Artikel zeigt dir auf Basis offizieller Informationen, wie du den Status liest, wie du ursachenbezogen vorgehst, welche die häufigste Windows-Falle ist und wie der Diagnose-Workflow aussieht.
Die wichtigsten Punkte vorab. (1) Sieh dir zuerst den Status mit /mcp (und claude mcp list) an — failed (Startfehler), needs authentication (Authentifizierung) und pending approval (wartet auf Genehmigung) erfordern jeweils völlig unterschiedliche Lösungen. (2) Bei lokal (stdio) sind die üblichen Übeltäter Pfade und Umgebungsvariablen sowie das Windows-npx-Problem. (3) Bei remote (HTTP) ist der übliche Übeltäter OAuth. (4) Wenn du nicht weiterkommst, führe claude --debug mcp aus, um die Fehlerausgabe des Servers (stderr) zu sehen. Verhalten und Standardwerte ändern sich je nach Version, prüfe daher gegen die aktuelle offizielle Dokumentation.
Der Status verrät die Lösung
— failed / needs auth / pending haben jeweils eine andere Heilung
✗ failed = ein lokales Startproblem, △ needs auth = Remote-Authentifizierung, ⏸ pending = wartet auf Genehmigung.
Wirf nicht alles unter „verbindet nicht" in einen Topf — klassifiziere zuerst nach Status; das ist der kürzeste Weg.
1. Was dieser Fehler bedeutet
MCP-Server gibt es in zwei grundlegenden Verbindungstypen. (1) stdio (lokal) — Claude Code startet den Befehl des Servers als Unterprozess auf deinem Rechner und kommuniziert über Standard-Ein-/Ausgabe. (2) HTTP (remote) — es verbindet sich über eine URL mit einem Cloud-Server (das ältere SSE ist veraltet). Was „verbindet nicht" bedeutet, hängt stark vom Typ ab.
Ein lokaler (stdio) Fehler ist fast immer „der Befehl selbst konnte nicht gestartet werden" — falscher Pfad, npx wird nicht aufgelöst (besonders unter Windows) oder der Server stürzt sofort ab, weil eine erforderliche Umgebungsvariable fehlt. Ein Remote-Fehler (HTTP) bedeutet meist „OAuth wurde nicht abgeschlossen" — der Server gibt 401/403 zurück und zeigt needs authentication an. Und wenn es keines von beidem ist, die Konfiguration aber keine Wirkung zeigt, ist der Speicherort der Konfigurationsdatei, ein JSON-Tippfehler oder die Projektgenehmigung verdächtig.
Der erste Schritt lautet daher: „/mcp öffnen, den Status lesen und feststellen, welche der drei Familien vorliegt." Jeden Fehler als generisches „verbindet nicht" zu behandeln und planlos herumzuprobieren, ist der Umweg. Der nächste Abschnitt behandelt, wie man den Status liest.
2. Zuerst den Status mit /mcp lesen
Führe 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:
| Status | Bedeutung | Wo zuerst nachsehen |
|---|---|---|
| ✓ connected | Verbunden. Anzahl der Werkzeuge daneben angezeigt | Wenn die Werkzeuganzahl 0 ist: „verbunden, aber keine Werkzeuge" → erneut verbinden / debuggen |
| ✗ failed | Start fehlgeschlagen oder Wiederholungen aufgebraucht | Lokaler Start = Befehl, Pfad, npx, Umgebungsvariablen (§3, §4) |
| △ needs authentication | Remote hat 401/403 zurückgegeben. OAuth nicht erledigt | Aus /mcp die Authentifizierung ausführen (im Browser genehmigen) |
| ⏸ pending approval | Wartet auf Genehmigung eines Projekt-Servers aus .mcp.json | In /mcp genehmigen. Bei versehentlicher Ablehnung: claude mcp reset-project-choices |
| ✗ rejected | Ein Projekt-Server, den du zuvor abgelehnt hast | Genauso (reset-project-choices zum erneuten Genehmigen) |
Der Kernpunkt: „failed = ein Startproblem, needs authentication = Authentifizierung, pending = Genehmigung" — der Status legt dein Vorgehen eindeutig fest. Ein häufig übersehener Fall ist „verbunden, aber 0 Werkzeuge" — der Server ist gestartet, gibt aber keine Werkzeugliste zurück; gehe zu einem erneuten Verbinden über oder prüfe die Logs mit claude --debug mcp.
3. Hauptursachen für Fehler und ihre Behebung
Hier sind die typischen Ursachen für failed (lokaler Startfehler) und für Konfigurationsprobleme, jeweils mit der passenden Lösung.
Hauptauslöser für failed / Konfigurationsprobleme
spawn ... ENOENT.env (in .mcp.json oder --env). Das env aus settings.json erreicht MCP NICHT.MCP_TIMEOUT (ms) beim Start, z. B. MCP_TIMEOUT=10000 claude..mcp.json gehört in das Repo-Wurzelverzeichnis (nicht unter .claude/, nicht in settings.json). Ein undefiniertes ${VAR} lässt das Parsen der Konfiguration scheitern.needs authentication. OAuth aus /mcp. Beachte: Ein abgelehnter statischer Auth-Header wird als failed gemeldet.
Bei lokal prüfe in dieser Reihenfolge: 1) Pfad → 2) Umgebungsvariablen → 4) Konfigurationsort.
Bei remote ist 6) Authentifizierung nahezu alles. Auch die Windows-Falle im nächsten Abschnitt ist sehr häufig.
Eine Projekt-.mcp.json kann über git geteilt werden und fragt beim ersten Mal nach Genehmigung. Wenn du diese Eingabeaufforderung versehentlich wegklickst, bleibt der Server deaktiviert (pending/rejected). Führe claude mcp reset-project-choices aus, um die Genehmigung erneut durchzuführen. Kombiniere dies mit den MCP-Grundlagen und der Agent-zu-Agent-Kommunikation A2A, um das Gesamtbild der Konnektivität zu erfassen.
4. Wenn es unter Windows fehlschlägt (die häufigste Falle)
Unter nativem Windows ist es extrem häufig, dass npx-basierte MCP-Server mit spawn npx ENOENT / Failed to connect nicht verbinden. Die Ursache: Das Windows-npx ist in Wirklichkeit ein Batch-Wrapper (npx.cmd), und der Prozess-Spawn von Node kann eine .cmd-Datei nicht direkt auflösen.
Lösung: in cmd /c einpacken
Lass command auf cmd statt direkt auf npx verweisen und übergib /c npx ... als Argumente:
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@scope/your-mcp-server"]
}Oder führe es unter WSL aus, was zuverlässig funktioniert. Wenn where npx einen Pfad anzeigt und es trotzdem fehlschlägt, ist zunächst dieses .cmd-Problem zu vermuten. Einige versionsabhängige Vorkommnisse könnten in späteren Releases behoben sein, versuche daher auch ein Update auf die neueste Version.
5. Der Diagnose-Workflow
Wenn die Ursache unklar ist, arbeite von oben nach unten. Der Trick: Bestätige, dass der Server eigenständig läuft, bevor du Claude Code die Schuld gibst.
Von oben nach unten eingrenzen
/mcp und claude mcp list / get, um den Status zu prüfen (failed vs. auth vs. pending).claude --debug mcp, um den stderr (Fehlerausgabe) des Servers zu lesen. Der Absturzgrund steht meist genau hier.npx ... in derselben Shell?). Falls nicht, liegt das Problem vor Claude Code.npx @modelcontextprotocol/inspector) — inspiziere seine Werkzeugliste und rufe Werkzeuge in einer Oberfläche auf.mcp*.log. /doctor prüft ebenfalls.
Die Regel: Bestätige zuerst „läuft der Server eigenständig?"
Sobald das geklärt ist, grenzt sich der Rest auf Konfiguration (Pfad, env, Speicherort) oder Authentifizierung ein.
Hinweis: Zu viele MCP-Server hinzuzufügen, führt dazu, dass Werkzeugdefinitionen den Kontext auffressen (besonders bei Always-Load-Konfigurationen). Claude Code lädt Werkzeugdefinitionen standardmäßig verzögert per Werkzeugsuche, sodass die Auswirkung gering ist, dennoch ist es ratsam, Server zu deaktivieren, die du nicht nutzt. Eine Überlastung des Kontexts kann sogar Prompt is too long auslösen.
6. Checkliste zur Vorbeugung
Gewohnheiten, um bei MCP-Verbindungen nicht hängenzubleiben.
(1) Gib lokale Skripte mit absoluten Pfaden an. (2) Lege Server-Schlüssel in das serverspezifische env (nicht in settings.json). (3) Packe unter Windows mit cmd /c npx ... ein (oder nutze WSL). (4) Halte .mcp.json im Repo-Wurzelverzeichnis; achte auf JSON-Syntax und undefiniertes ${VAR}. (5) Server dürfen nicht nach stdout loggen (nutze stderr). (6) Nach Konfigurationsänderungen neu laden (Desktop vollständig neu starten; Projekt-Server erneut genehmigen). (7) Wenn du nicht weiterkommst, grenze mit claude --debug mcp und einem eigenständigen Server-Start ein und aktualisiere bei Bedarf auf die neueste Version.
Fazit
Bei MCP-Server-Verbindungsfehlern von Claude Code ist der kürzeste Weg, nach dem /mcp-Status in drei Familien zu klassifizieren. ✗ failed ist ein lokales Startproblem (Pfad, Umgebungsvariablen, Timeout, Konfigurationsort — und unter Windows npx mit cmd /c einpacken), △ needs authentication ist Remote-OAuth (aus /mcp authentifizieren), und ⏸ pending approval ist ein Projekt-Server, der auf Genehmigung wartet (in /mcp genehmigen; eine versehentliche Ablehnung behebst du mit claude mcp reset-project-choices).
Diagnostiziere in dieser Reihenfolge: (1) Status mit /mcp -> (2) stderr mit claude --debug mcp -> (3) eigenständiger Start -> (4) MCP Inspector -> (5) Desktop vollständig neu starten. Bestätige, dass der Server eigenständig läuft, bevor du Claude Code die Schuld gibst, dann grenzt sich der Rest auf Konfiguration oder Authentifizierung ein. Nur drei Gewohnheiten — Umgebungsvariablen in das serverspezifische env, .mcp.json ins Repo-Wurzelverzeichnis, Logs nach stderr — reduzieren Vorfälle drastisch. Verwandt: Was ist MCP, MCP-Server monetarisieren, Claude-Code-Fehlerübersicht.
FAQ
Q. /mcp zeigt „failed" an. Wo fange ich an?
A. failed ist meist ein Startfehler eines lokalen (stdio) Servers. Prüfe in dieser Reihenfolge: (1) den Pfad des Befehls/Skripts (nutze absolute Pfade), (2) erforderliche Umgebungsvariablen (lege sie in das serverspezifische env) und (3) unter Windows mit cmd /c npx ... einpacken. Ist die Ursache weiterhin unklar, lies den stderr des Servers mit claude --debug mcp und teste zuerst, ob der Server in derselben Shell eigenständig startet.
Q. Es zeigt „needs authentication" und die Werkzeuge funktionieren nicht.
A. Das ist ein Remote-Server (HTTP), der eine Authentifizierung verlangt (401/403). Öffne /mcp und führe die Authentifizierung für diesen Server aus; es geht zur OAuth-Genehmigung im Browser über. Danach werden Tokens sicher gespeichert und automatisch erneuert. Beachte, 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.
Q. Unter Windows verbindet mein npx-Server einfach nicht.
A. Das Windows-npx ist in Wirklichkeit ein Batch-Wrapper (npx.cmd), der oft mit spawn npx ENOENT nicht startet. Ändere command zu cmd und args zu ["/c","npx","-y","package-name"], um es einzupacken. Die Ausführung unter WSL ist ebenfalls zuverlässig. Wenn where npx einen Pfad anzeigt und es trotzdem fehlschlägt, ist es fast sicher dieses .cmd-Problem. Es könnte in neueren Versionen behoben sein, versuche daher auch ein Update.
Q. Es ist „connected", zeigt aber 0 Werkzeuge.
A. Der Server ist erfolgreich gestartet, gibt aber keine Werkzeugliste zurück. Eine häufige Ursache ist ein stdio-Server, der Logs nach stdout schreibt und das Protokoll beschädigt — schicke Logs immer nach stderr. Verbinde zuerst aus /mcp erneut; behebt das nichts, prüfe die Ausgabe des Servers mit claude --debug mcp.
Q. Ich habe einen Server konfiguriert, aber er erscheint nicht in /mcp.
A. Der Speicherort der Konfigurationsdatei ist die wahrscheinliche Ursache. Ein geteilter Projekt-Server gehört in .mcp.json im Repo-Wurzelverzeichnis (er wird nicht unter .claude/ oder innerhalb von settings.json gelesen). Auch ein undefiniertes ${VAR} lässt das Parsen der Konfiguration scheitern. Projekt-Server brauchen eine erstmalige Genehmigung; wenn du die Eingabeaufforderung wegklickst, bleibt er pending — wiederhole sie mit claude mcp reset-project-choices.
