Claude Code MCP Config: .mcp.json, Scopes und Vorrang

Du hast einen MCP-Server mit claude mcp add eingerichtet, er läuft, und dann klont ein Kollege das Repo und sieht nichts davon. Oder umgekehrt: Ein Server, den du gar nicht mehr willst, taucht in jedem Projekt wieder auf. In beiden Fällen lohnt der Blick auf den Scope. Claude Code kennt drei Orte für MCP-Konfiguration, und die Regeln, welcher davon gewinnt, sind strenger, als die meisten annehmen. Grundlage hier ist die offizielle MCP-Doku von Claude Code.

Drei Scopes, zwei Dateien

Jedes claude mcp add und claude mcp add-json schreibt in den Local Scope, solange du nicht --scope project oder --scope user mitgibst.

• Local (Default): lädt nur im aktuellen Projekt, bleibt privat. Gespeichert in ~/.claude.json unter dem Pfad des Projekts. Richtig für experimentelle Server und alles mit persönlichen Credentials.
• Project: lädt nur im aktuellen Projekt, wird aber über .mcp.json im Repo-Root geteilt. Claude Code legt die Datei bei Bedarf selbst an. Die Datei gehört ins Version Control.
• User: lädt in allen deinen Projekten, bleibt privat, liegt ebenfalls in ~/.claude.json. Gedacht für persönliche Utilities, die du überall brauchst.

Wichtig für das Debugging: Local und User teilen sich dieselbe Datei. Ein cat ~/.claude.json zeigt dir beide, nur an unterschiedlichen Stellen.

Vorrang: ganzer Eintrag statt Merge

Steht derselbe Server an mehreren Stellen, verbindet sich Claude Code genau einmal, und zwar mit der Definition aus der Quelle mit dem höchsten Rang:

1. Local
2. Project
3. User
4. Plugin-Server
5. claude.ai Connectors

Der Trade-off, über den man stolpert: Es wird nicht gemerged. Überschreibst du im Local Scope einen Projekt-Server, um nur einen Header zu ändern, gilt dein kompletter lokaler Eintrag. Alles, was das Team später in .mcp.json ändert, siehst du nicht mehr.

Zwischen den drei Scopes matcht Claude Code per Name. Plugins und Connectors werden dagegen per Endpoint verglichen: Zeigen sie auf dieselbe URL oder denselben Command wie ein Server weiter oben, gelten sie als Duplikat. Groß-/Kleinschreibung von Scheme und Host, ein Default-Port wie :443 oder ein Slash am Ende machen keinen Unterschied, ein anderer Pfad oder Query-String schon. Ein Server, den deine Organisation über managedMcpServers bereitstellt, steht über allem (ab v2.1.259).

Gleicher Name in mehreren Scopes mit unterschiedlichen Endpoints erzeugt eine Warnung in claude mcp list und /mcp. Weil OAuth-Logins pro Endpoint gespeichert werden, musst du dich sonst in jedem Projekt separat anmelden. Aufräumen mit claude mcp remove <name> --scope <scope>.

.mcp.json teilbar machen mit ${VAR}

Damit .mcp.json ins Repo darf, gehören Secrets und maschinenspezifische Pfade nicht hinein. Claude Code expandiert Variablen in command, args, env, url und headers:

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

Drei Details, die in der Praxis Zeit kosten:

• Fehlender Wert ohne Default: Der Server lädt trotzdem, mit dem unexpandierten ${VAR}-Text. claude mcp list warnt und nennt die Variable.
• Leerer String zählt als gesetzt: API_BASE_URL="" ergibt die URL /mcp, nicht den Default. Variable unsetten statt leeren.
• Credential-Variablen bleiben leer: In url und headers von Remote-Servern liest Claude Code eigene und Cloud-Credentials wie ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY oder NPM_TOKEN immer als leer, auch ein :-default wird ignoriert. Das verhindert, dass ein fremdes .mcp.json deine Keys an einen Server schickt. Der Server antwortet dann meist mit 401. Brauchst du so einen Wert, kopierst du ihn in eine eigene Variable.

Außerdem: Ein Entry mit url, aber ohne type, wird als stdio-Server gelesen und übersprungen. streamable-http wird als Alias für http akzeptiert. Versteckte Whitespace-Zeichen, etwa ein Newline hinter einem eingefügten Token, meldet Claude Code als Warnung, trimmt sie aber nicht.

Approval, Trust und Headless

Projekt-Server aus .mcp.json brauchen in interaktiven Sessions eine Freigabe. Bis dahin zeigt claude mcp list sie als ⏸ Pending approval. Zurücksetzen lässt sich das mit claude mcp reset-project-choices. Ein geklontes Repo kann sich nicht selbst freigeben: enableAllProjectMcpServers oder enabledMcpjsonServers in der eingecheckten .claude/settings.json werden ignoriert, solange der Ordner nicht als vertrauenswürdig bestätigt ist. Freigaben aus ~/.claude/settings.json, Managed Settings und --settings gelten dagegen auch dort.

Die Kehrseite: Bei claude -p, im Agent SDK und in Cloud-Sessions außerhalb eines Projekts gibt es keinen Prompt, Projekt-Server werden ohne Rückfrage geladen. Gleiches gilt für bypassPermissions mit skipDangerousModePermissionPrompt. Wenn dein CI-Job fremde Branches auscheckt, ist das relevant. Dein Werkzeugkasten:

• disabledMcpjsonServers blockt einen Server in jedem Permission Mode.
• --setting-sources (bzw. settingSources im SDK) schließt Projekt-Settings ganz aus.
• --strict-mcp-config nutzt nur die Server aus --mcp-config. Dass dabei nicht mehr auf Approval für ungeladene Projekt-Server gewartet wird, gilt erst ab v2.1.246.

Wie du Tool-Aufrufe zusätzlich einschränkst, steht in settings.json Permissions. Für Server mit Datenbankzugriff lohnt der Blick auf MCP-Server Guardrails.

Was das für deinen Workflow bedeutet

Behandle .mcp.json wie Code: nur Server, die das ganze Repo braucht, keine Secrets, nur ${VAR}-Referenzen, jeder Remote-Eintrag mit explizitem type. Persönliches gehört in Local oder User. Lokale Overrides eines Projekt-Servers sind eine Falle, weil sie den Team-Eintrag komplett verdecken. Und für Headless-Läufe definierst du die erlaubten Server explizit, statt dich auf einen Approval-Prompt zu verlassen, der dort nie erscheint. Wer Bash-Zugriff zusätzlich einhegen will, findet das in Claude Code Sandbox.

Die Scope-Regeln sind schnell erklärt, die Wechselwirkung mit Settings, Trust und CI ist es nicht. Du willst wissen, ob deine .mcp.json, deine Freigaben und dein CI-Setup zusammenpassen? Fordere ein Agent-Setup-Review an.