MCP debuggen wenn nichts geht, die 10 Checks die 90 Prozent der Faelle loesen

Du hast einen MCP-Server in der Config. Du startest Claude Code. Tippst /mcp. Da steht "no servers" oder der Server ist da aber die Tools fehlen. Oder noch besser: der Server steht da als "connected" aber bei jedem Tool-Call kommt "tool not found". Das ist die Stunde in der die meisten Leute aufgeben oder anfangen wahllos Pfade umzuschreiben.

Ich geb Dir hier die Reihenfolge die ich selbst durchgehe. Zehn Checks, jeder dauert ein bis zwei Minuten, in der Reihenfolge so dass Du im Schnitt nach drei Schritten weisst woran es liegt.

Schritt 1, claude --debug einmal komplett mitlesen

Beende Claude Code, starte neu mit claude --debug. In der Konsole läuft jetzt verbose Logging mit. Achte auf drei Zeilen-Typen: "MCP server connecting", "tool discovery", "MCP error". Die letzten zwei Zeilen vor dem ersten Error sagen Dir fast immer was kaputt ist.

Die offizielle Doku zu Debug Logging steht in der MCP Integration Skill: "running claude --debug ... will reveal details about MCP server connection attempts, the process of tool discovery, authentication flows, and any errors". Das ist der einzige Schritt den Du wirklich nicht uberspringen darfst.

Schritt 2, /mcp im Chat aufrufen

In der laufenden Session: tipp /mcp. Du bekommst eine Liste Deiner Server mit Status. "connected" heisst Verbindung steht. "failed" heisst die Verbindung kam nie zustande. "no tools" heisst verbunden aber keine Tools entdeckt. Jeder dieser drei Zustaende hat eine andere Diagnose.

Schreib Dir den Status auf bevor Du irgendwas aenderst. Wenn Du einmal blind die Config umschreibst weisst Du nicht mehr ob der vorige Zustand "failed" oder "no tools" war.

Schritt 3, der Command muss existieren und ausfuehrbar sein

Bei stdio-Servern (also npx, node, python) macht Claude Code im Hintergrund einen spawn auf den Command den Du in der Config angegeben hast. Wenn der Command nicht im PATH ist, oder die node_modules nicht installiert sind, oder das Script keine execute Bits hat, kommt nichts zurück.

Test: kopier den exakten Command aus Deiner mcp-Config in Dein Terminal und fuehr ihn manuell aus. Wenn der Server in Deinem Terminal nicht startet, startet er auch in Claude Code nicht. Pruef Path, pruef Permissions (chmod +x), pruef ob node_modules installiert sind.

Schritt 4, stdout muss sauber sein

stdio-MCP-Server kommunizieren ueber stdin/stdout im JSON-RPC-Format. Wenn Dein Server beim Start ein console.log oder print('starting...') auf stdout schreibt, ist das in den JSON-Stream eingemischt und Claude Code kann nichts parsen.

Quote aus den MCP-Integration-Docs zu stdio-Troubleshooting: "ensure that your server correctly uses stdin/stdout for MCP messages and check for any unintended print or console.log statements that might interfere with the JSON-RPC stream".

Fix: alle Logging-Statements in Deinem MCP-Code auf stderr umleiten. console.error statt console.log in Node, sys.stderr in Python. Plus ein "no banner on startup" Setting falls Dein Framework eines ausgibt.

Schritt 5, der Pfad in der Config ist absolut

Relative Pfade in mcp-Configs sind eine der haeufigsten Fehlerquellen. "./meine-skripte/server.js" funktioniert nicht weil Claude Code von einem anderen working directory startet als Du denkst. Schreib den Pfad voll aus, /home/user/projekt/meine-skripte/server.js.

Gleiches Spiel mit ENV-Variablen: $HOME wird in der Config nicht expandiert wenn Du es als String reinschreibst. Entweder den vollen Pfad oder die env-Section in der Config nutzen wenn Dein MCP-Framework das unterstuetzt.

Schritt 6, Restart nach jeder Config-Anderung

Aenderungen an der mcp-Config werden NICHT live nachgeladen. Aus den Troubleshooting-Docs: "If issues persist after making configuration changes, restart Claude Code to apply the updates". Komplett beenden, neu starten. Reload reicht nicht.

Klingt trivial. Ist aber der Grund warum Leute eine Stunde lang glauben "der Pfad muss noch falsch sein" obwohl der Pfad seit zehn Minuten richtig ist und sie es nur nicht gemerkt haben weil keine neue Session lief.

Schritt 7, HTTP-MCP, der Port ist offen und Auth stimmt

Bei HTTP-MCP-Servern (Remote, Cloud-Run, eigener Endpoint) sind die typischen Failure-Modi: Port nicht erreichbar, falsche URL, fehlender Auth-Header, abgelaufenes Token. curl auf den Health-Endpoint ist Dein erster Test, dann schau in den Server-Logs.

Wichtig: 401 oder 403 sind NICHT "broken". Das sind Auth-Required-Endpoints, Dein Token war falsch oder fehlt. "connection refused" oder "timeout" sind die echten Connection-Probleme.

Schritt 8, der Tool-Name matched exakt

Aus den Tool-Usage-Docs: "Verify that tool names match exactly, as they are case-sensitive". Wenn Dein Server nex_entity_create exportiert und Du in der allow-Liste mcp__nex__nexEntityCreate stehen hast, matched das nicht. Tool nicht verfuegbar.

Pruefliste: groß-klein-Schreibung, Underscores vs Camelcase, Server-Prefix. Bei Plugins und Bundles auch das namespace-Prefix. Wenn unklar: einmal /mcp aufrufen und die Tool-Namen genau wie sie da stehen kopieren.

Schritt 9, die Permissions in settings.json blockieren das Tool

Du hast vielleicht eine permissions.deny oder permissions.allow Liste die das Tool implizit blockiert. "mcp__*" als deny blockiert alle MCP-Tools. Eine zu enge allow-Liste lässt nur ein paar durch.

Test: pruef in .claude/settings.json (Projekt) und ~/.claude/settings.json (Global) ob es eine permissions-Sektion gibt die Dein Tool ausschliesst. Plan Mode sagt Dir auch im Verlauf "tool not allowed" wenn das der Fall ist.

Schritt 10, das Permission-Mode-Missverstaendnis

Wenn Du in Plan Mode bist, läuft kein Tool, auch wenn alles richtig konfiguriert ist. Du tippst eine Aufgabe, Claude antwortet mit einem Plan, Du siehst keinen Tool-Call und denkst "der Server ist kaputt". In Wahrheit funktioniert alles, Du bist nur in der falschen Permission.

Shift+Tab durchcyclen bis "default" oder "acceptEdits" steht. Dann nochmal versuchen. Wer einen ganzen Tag verzweifelt nach einem MCP-Bug sucht und am Ende war es Plan Mode, der vergisst es nie wieder. Frag mich woher ich das weiss.

Was als naechstes

Wenn Dein Server wieder läuft, lies das Recipe phase-7-mcp-patterns/7.5-error-handling für ein vernuenftiges Error-Pattern in Deinem MCP-Code. Für eigene Server lohnt sich der Playbook erster-mcp-server-in-90-minuten plus mcp-server-publishen wenn Du distribuieren willst. Und wenn Du oft zwischen mehreren Servern jonglierst: tool-sprawl-vermeiden hilft die Last gering zu halten.

Source

• Debug Logging und MCP Integration: https://code.claude.com/docs/en/mcp und https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md
• stdio Troubleshooting: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md
• Tool-Usage und Restart-Hinweis: https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md
• Plan Mode und Permission-Modi: https://code.claude.com/docs/en/interactive-mode