Claude Code MCP-Konfiguration: .mcp.json, Geltungsbereiche, Fehlerbehebung

2026-09-09 Aktualisiert: 2026-09-14

Claude Code liest MCP-Server aus zwei Dateien: .mcp.json im Projektwurzelverzeichnis für Server, die mit dem Team geteilt werden, und ~/.claude.json für Ihre eigenen lokalen und benutzerbezogenen Server. Beide verwenden dasselbe Objekt mcpServers, in dem jeder Eintrag einen type von http, sse, ws oder stdio nennt, und ein Server, der nicht erscheint, hat fast immer einen falschen type, eine nicht expandierte Umgebungsvariable oder eine nie abgeschlossene Anmeldung als Ursache.

Das .mcp.json-Format

Eine Projektdatei mit einem entfernten und einem lokalen Server sieht so aus:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Das Feld type ist immer dann erforderlich, wenn url vorhanden ist. Eine url ohne type wird als Konfigurationsfehler gemeldet (die Meldung fordert Sie auf, "type": "http", sse oder ws zu ergänzen), was eine ältere und deutlich weniger hilfreiche Beschwerde über ein fehlendes command abgelöst hat. Der Wert streamable-http wird als Alias für http akzeptiert. Ein entfernter Server, der eine feste Anmeldeinformation braucht, nimmt ein Objekt headers entgegen; ein lokaler nimmt command, args und env. Der optionale timeout ist eine Obergrenze pro Tool-Aufruf in Millisekunden. WebSocket-Server lassen sich nur in einer Datei oder über claude mcp add-json deklarieren; das Flag --transport akzeptiert kein ws.

Der Befehl claude mcp add mit --scope project schreibt diese Datei für Sie, händisches Bearbeiten ist also nur für Felder nötig, die der Befehl nicht anbietet, oder wenn Sie die Änderung lieber in einem Pull Request prüfen wollen.

Geheimnisse aus der Datei heraushalten

Da .mcp.json zum Committen gedacht ist, sollten Tokens nicht hineingeschrieben werden. Claude Code expandiert Umgebungsvariablen in command, args, env, url und headers: ${VAR} übernimmt den Wert der Variable, und ${VAR:-default} weicht auf den Vorgabewert aus, wenn sie nicht gesetzt ist.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Eine referenzierte Variable, die nicht gesetzt ist und keinen Vorgabewert hat, hindert den Server nicht am Laden; der wörtliche Text ${API_KEY} wird unverändert gesendet, und claude mcp list gibt eine Warnung aus. Diese Warnung ist das Erste, wonach Sie suchen sollten, wenn ein Server sich verbindet, aber jeder Aufruf als nicht autorisiert abgelehnt wird.

Bei einem Server, der OAuth unterstützt, gibt es überhaupt nichts zu verbergen: Lassen Sie den Eintrag nur mit type und url, und jede Person meldet sich einmal über /mcp an. Das Token wird pro Nutzer außerhalb des Repositorys gespeichert und durch claude mcp remove wieder entfernt.

Genehmigung, Rangfolge und verwaltete Server

Sieht Claude Code einen Server zum ersten Mal in der .mcp.json eines Projekts, fragt eine interaktive Sitzung, ob er verwendet werden soll; nicht-interaktive Läufe (claude -p, das Agent SDK, Cloud-Sitzungen) laden ihn ohne Nachfrage. Die Entscheidung wird pro Projekt gemerkt; claude mcp reset-project-choices vergisst sie wieder, sodass Sie nach einer Änderung erneut genehmigen können.

Ist ein Name an mehreren Stellen definiert, gilt die Reihenfolge lokaler Geltungsbereich, dann Projekt-Geltungsbereich, dann Benutzer-Geltungsbereich, dann von Plugins bereitgestellte Server, dann Connectors von claude.ai. Der gesamte gewinnende Eintrag wird verwendet. Organisationen können über eine verwaltete Konfigurationsdatei oder die Einstellung managedMcpServers (Claude Code 2.1.259 oder neuer) eine feste Server-Liste durchsetzen; diese rangieren über jedem Geltungsbereich auf Benutzerebene, und eine verwaltete Datei, die ausschließliche Kontrolle beansprucht, lässt claude mcp add mit einer Meldung ablehnen, dass eine Enterprise-Konfiguration aktiv ist. Erlaub- und Sperrlisten (allowedMcpServers, deniedMcpServers) können außerdem einschränken, welche URLs oder Befehle Nutzer hinzufügen dürfen, und eine Sperre gewinnt immer.

Die Statusausgabe lesen

claude mcp list meldet jeden Server als verbunden, Authentifizierung erforderlich, Verbindung fehlgeschlagen, ausstehende Genehmigung, über disabledMcpjsonServers abgelehnt, oder für dieses Projekt deaktiviert. Ein paar weniger offensichtliche Warnungen, die ausgegeben werden, lohnt es sich zu kennen: versteckte führende oder nachgestellte Leerzeichen in einem Wert (ein eingefügtes Token, das mit einem Zeilenumbruch endete), derselbe Name, der in zwei Geltungsbereichen auf unterschiedliche Endpunkte verweist, und eine Handvoll reservierter Namen, die für eigene Server nicht verwendet werden können. WebSocket-Server erscheinen in der Liste überhaupt nicht; prüfen Sie sie mit claude mcp get <name> oder /mcp.

Häufige Fehler und ihre Lösungen

Ein entfernter Server zeigt "Authentifizierung erforderlich" oder antwortet mit 401 oder 403. Öffnen Sie /mcp, wählen Sie den Server aus und schließen Sie die Browser-Anmeldung ab, oder führen Sie claude mcp login <name> aus. Verwendet der Server ein statisches Token, prüfen Sie den Header-Wert und die Warnung über nicht expandierte Variablen.
Ein lokaler Server verbindet sich beim Start nicht. Führen Sie seinen Befehl von Hand in derselben Shell aus, um den echten Fehler zu sehen; die üblichen Ursachen sind eine fehlende Laufzeitumgebung, ein Paket, das installiert werden muss, oder eine erforderliche Umgebungsvariable. Langsam startende Server treffen auf das Start-Limit, das MCP_TIMEOUT in Millisekunden anhebt, zum Beispiel MCP_TIMEOUT=10000 claude.
Der Server verbindet sich, aber ein Tool liefert ein abgeschnittenes Ergebnis. Die Tool-Ausgabe ist standardmäßig bei 25.000 Tokens gedeckelt, mit einer Warnung ab 10.000; MAX_MCP_OUTPUT_TOKENS hebt die Grenze an.
Tools scheinen in der Unterhaltung zu fehlen. Claude Code stellt Tool-Definitionen zurück, bis sie gebraucht werden, um den Kontext klein zu halten, sodass zu Beginn nur Namen und Server-Anweisungen laden; der Assistent findet sie trotzdem, sobald eine Anfrage passt. Setzen Sie "alwaysLoad": true auf einem Server-Eintrag, wenn Sie seine vollständigen Definitionen vom ersten Zug an präsent haben wollen.
Ein entfernter Server bricht mitten in der Sitzung ab. Claude Code versucht eine abgebrochene Verbindung bis zu fünf Mal mit wachsenden Verzögerungen erneut und eine fehlgeschlagene erste HTTP-Verbindung bis zu drei Mal, aber nicht bei Authentifizierungsfehlern und nicht bei lokalen Servern, ein Authentifizierungsfehler behebt sich also nicht von selbst.

Die Konfiguration gegen einen Live-Dienst testen

Der schnellste Weg, die .mcp.json eines Projekts zu validieren, ist ein Server, dessen Antworten Sie unabhängig prüfen können. Mit committetem { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } und jedem Entwickler, der sich einmal über /mcp angemeldet hat, muss eine Anfrage wie "führe eine HTTP-Prüfung auf unserer Staging-URL aus Europa und Asien aus" mit echten Statuscodes und Antwortzeiten von HostTrackers Prüfpunkten zurückkommen, was entweder beweist, dass die Datei korrekt gelesen wird, oder den Fehler auf die Anmeldung eingrenzt. Die begleitende Anleitung, wie man einen MCP-Server zu Claude Code hinzufügt, behandelt den Kommandozeilen-Weg und die Geltungsbereiche ausführlicher.