Claude Code mit Tools über MCP verbinden

Erfahren Sie, wie Sie Claude Code mit Ihren Tools über das Model Context Protocol verbinden.

Claude Code kann sich über das Model Context Protocol (MCP), einen offenen Standard für KI-Tool-Integrationen, mit Hunderten von externen Tools und Datenquellen verbinden. MCP-Server geben Claude Code Zugriff auf Ihre Tools, Datenbanken und APIs.

Verbinden Sie einen Server, wenn Sie feststellen, dass Sie Daten aus einem anderen Tool wie einem Issue-Tracker oder einem Überwachungs-Dashboard in den Chat kopieren. Nach der Verbindung kann Claude direkt auf dieses System zugreifen und handeln, anstatt mit dem zu arbeiten, was Sie einfügen.

Wenn Sie Ihren ersten Server verbinden, beginnen Sie mit der MCP-Schnellstartanleitung für eine Schritt-für-Schritt-Anleitung. Diese Seite ist die vollständige Referenz.

Was Sie mit MCP tun können

Mit verbundenen MCP-Servern können Sie Claude Code auffordern:

• Funktionen aus Issue-Trackern implementieren: „Füge die in JIRA-Issue ENG-4521 beschriebene Funktion hinzu und erstelle einen PR auf GitHub.“
• Überwachungsdaten analysieren: „Überprüfe Sentry und Statsig, um die Nutzung der in ENG-4521 beschriebenen Funktion zu überprüfen.“
• Datenbanken abfragen: „Finde E-Mail-Adressen von 10 zufälligen Benutzern, die die Funktion ENG-4521 verwendet haben, basierend auf unserer PostgreSQL-Datenbank.“
• Designs integrieren: „Aktualisiere unsere Standard-E-Mail-Vorlage basierend auf den neuen Figma-Designs, die in Slack gepostet wurden“
• Workflows automatisieren: „Erstelle Gmail-Entwürfe, die diese 10 Benutzer zu einer Feedback-Sitzung zur neuen Funktion einladen.“
• Auf externe Ereignisse reagieren: Ein MCP-Server kann auch als Kanal fungieren, der Nachrichten in Ihre Sitzung pusht, sodass Claude auf Telegram-Nachrichten, Discord-Chats oder Webhook-Ereignisse reagiert, während Sie weg sind.

MCP-Server finden und erstellen

Durchsuchen Sie überprüfte Konnektoren im Anthropic Directory. Directory-Konnektoren verwenden die gleiche MCP-Infrastruktur wie Claude Code, sodass Sie jeden dort aufgelisteten Remote-Server mit claude mcp add hinzufügen können.

[!WARNING]

Überprüfen Sie, dass Sie jedem Server vertrauen, bevor Sie ihn verbinden. Server, die externe Inhalte abrufen, können Sie dem Risiko von Prompt-Injection aussetzen.

Um Ihren eigenen Server zu erstellen, lesen Sie das MCP-Server-Handbuch für Protokoll-Grundlagen und die Claude-Konnektoren-Dokumentation zum Erstellen für Authentifizierung, Tests und Directory-Einreichung.

Sie können Claude auch einen Server für Sie mit dem offiziellen mcp-server-dev Plugin erstellen lassen.

1. Installieren Sie das Plugin

Folgen Sie in der VS Code-Erweiterung oder der Desktop-App anstelle dieses Schritts der Anleitung Ein Plugin installieren. Starten Sie in einem Terminal Claude Code, indem Sie claude ausführen, und geben Sie dann Folgendes in das Eingabefeld ein:

/plugin install mcp-server-dev@claude-plugins-official

Wenn die Installation fehlschlägt, beachten Sie die Meldung, die Claude Code meldet:

• Marketplace "claude-plugins-official" not found: Fügen Sie den Marketplace mit /plugin marketplace add anthropics/claude-plugins-official hinzu und versuchen Sie dann die Installation erneut.
• Plugin "<name>" not found in marketplace "claude-plugins-official": Ihre lokale Kopie des Marketplace-Katalogs ist möglicherweise veraltet. Aktualisieren Sie sie mit /plugin marketplace update claude-plugins-official und versuchen Sie dann die Installation erneut. Wenn der erneute Versuch dieselbe Meldung ausgibt, lesen Sie Plugin nicht im Marketplace gefunden.

Wenn die Installationszusammenfassung Run /reload-plugins to apply. meldet, führt Claude Code dieses Neuladen dann für Sie aus. Wenn das Neuladen warnt, dass Ihre nächste Nachricht die Konversation erneut lesen würde, führen Sie /reload-plugins --force aus.

2. Führen Sie den Build-Skill aus

/mcp-server-dev:build-mcp-server

Claude fragt nach Ihrem Anwendungsfall und erstellt einen Remote-HTTP- oder lokalen Stdio-Server.

MCP-Server installieren

MCP-Server können je nach Ihren Anforderungen auf verschiedene Weise konfiguriert werden:

Option 1: Einen Remote-HTTP-Server hinzufügen

HTTP-Server sind die empfohlene Option für die Verbindung mit Remote-MCP-Servern. Dies ist das am weitesten unterstützte Transportprotokoll für Cloud-basierte Dienste.

# Grundlegende Syntax
claude mcp add --transport http <name> <url>

# Echtes Beispiel: Mit Notion verbinden
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Beispiel mit Bearer-Token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Bei der Konfiguration von MCP-Servern über JSON in .mcp.json, ~/.claude.json oder claude mcp add-json akzeptiert das Feld type streamable-http als Alias für http. Die MCP-Spezifikation verwendet den Namen streamable-http für dieses Transportprotokoll, sodass Konfigurationen, die aus der Serverdokumentation kopiert werden, ohne Änderungen funktionieren.

Ein JSON-Eintrag mit einer url aber ohne type ist ein Konfigurationsfehler, da Claude Code einen Eintrag ohne type als Stdio-Server liest. Claude Code überspringt diesen Server und meldet MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry.

Nur eine SDK-Host-Anwendung, wie eine Agent SDK-Anwendung oder die Desktop-App, kann einen In-Process-Server vom Typ "type": "sdk" registrieren. Claude Code überspringt einen "type": "sdk"-Eintrag in .mcp.json, ~/.claude.json oder Einstellungen und meldet Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

Bei --output-format stream-json-Läufen meldet Claude Code auch einen übersprungenen --mcp-config-Eintrag im mcp_server_errors-Feld des system/init-Events, sodass Skripte erkennen können, dass der Server nie geladen wurde. Dies erfordert Claude Code v2.1.219 oder später.

Option 2: Einen Remote-SSE-Server hinzufügen

[!WARNING]

Das SSE-Transportprotokoll (Server-Sent Events) ist veraltet. Verwenden Sie stattdessen HTTP-Server, wo verfügbar.

Einige Dienste stellen weiterhin nur einen SSE-Endpunkt bereit. Fügen Sie diese mit demselben Befehl claude mcp add --transport http <name> <url> wie einen HTTP-Server hinzu. Claude Code versucht zuerst das HTTP-Transportprotokoll und wechselt zu SSE, wenn der Server es nicht akzeptiert. Der automatische Wechsel erfordert Claude Code v2.1.265 oder später.

Bei einer früheren Version oder um direkt über SSE zu verbinden, übergeben Sie stattdessen --transport sse:

# Grundlegende Syntax
claude mcp add --transport sse <name> <url>

# Echtes Beispiel: Mit Asana verbinden
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Beispiel mit Authentifizierungsheader
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Option 3: Einen lokalen Stdio-Server hinzufügen

Stdio-Server werden als lokale Prozesse auf Ihrem Computer ausgeführt. Sie sind ideal für Tools, die direkten Systemzugriff oder benutzerdefinierte Skripte benötigen.

Claude Code setzt CLAUDE_PROJECT_DIR in der Umgebung des erzeugten Servers auf das Projektstammverzeichnis, sodass Ihr Server projektrelative Pfade auflösen kann, ohne vom Arbeitsverzeichnis abhängig zu sein. Dies ist dasselbe Verzeichnis, das Hooks in ihrer CLAUDE_PROJECT_DIR-Variable erhalten. Lesen Sie es aus Ihrem Serverprozess, zum Beispiel process.env.CLAUDE_PROJECT_DIR in Node oder os.environ["CLAUDE_PROJECT_DIR"] in Python.

CLAUDE_PROJECT_DIR ist das stabile Projektstammverzeichnis und ändert sich nicht, wenn Sie während einer Sitzung Arbeitsverzeichnisse hinzufügen oder entfernen. Ein Server, der seinen eigenen Dateisystemzugriff auf einen Satz zulässiger Verzeichnisse beschränkt, sollte stattdessen die MCP-Anfrage roots/list implementieren. Claude Code antwortet auf roots/list mit dem Startverzeichnis der Sitzung plus jedem zusätzlichen Arbeitsverzeichnis, das Sie mit --add-dir, /add-dir oder der Einstellung additionalDirectories gewährt haben. Claude Code sendet notifications/roots/list_changed, wenn sich dieser Satz ändert.

Diese Variable wird in der Umgebung des Servers gesetzt, nicht in der Umgebung von Claude Code selbst. Daher erfordert das Referenzieren über ${VAR}-Expansion in command oder args eines projektgebundenen .mcp.json-Eintrags oder eines lokal- oder benutzergebundenen Servereintrags in ~/.claude.json einen Standard wie ${CLAUDE_PROJECT_DIR:-.}. Von Plugins bereitgestellte MCP-Konfigurationen ersetzen ${CLAUDE_PROJECT_DIR} direkt und benötigen keinen Standard.

# Grundlegende Syntax
claude mcp add [options] <name> -- <command> [args...]

# Echtes Beispiel: Airtable-Server hinzufügen
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!NOTE]

Bei Stdio-Servern trennt -- (Doppelstrich) Claudes eigene Optionen wie --transport, --env und --scope vom Befehl und den Argumenten, die den Server ausführen. Alles nach -- wird unverändert an den Server übergeben.

Zum Beispiel:

• claude mcp add --transport stdio myserver -- npx server → führt npx server aus
• claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → führt python server.py --port 8080 mit KEY=value in der Umgebung aus

Ohne -- würde Claude Code versuchen, die Flags des Servers wie --port oben als seine eigenen Optionen zu analysieren.

--env akzeptiert mehrere KEY=value-Paare. Wenn der Servername direkt nach --env kommt, liest die CLI den Namen als ein weiteres Paar und lehnt ihn ab. Platzieren Sie daher mindestens eine andere Option wie --transport stdio zwischen --env und dem Servernamen.

Wie Claude Code einen Stdio-Server stoppt

Wenn Claude Code die Verbindung zu einem Stdio-Server trennt, zum Beispiel wenn Ihre Sitzung endet, sendet es dem Serverprozess ein Signal und wartet kurz, bis er sich beendet, bevor es ihn zwangsweise stoppt. Wenn Ihr Server beim Herunterfahren seinen Zustand speichert oder Sperrdateien entfernt, behandeln Sie das Signal für Ihre Plattform und schließen Sie diese Arbeit innerhalb dieser Zeit ab:

• Unter macOS und Linux: Claude Code sendet SIGINT, dann SIGTERM, wenn der Prozess 100 Millisekunden später noch läuft, und nach weiteren 400 Millisekunden SIGKILL.
• Unter Windows: Claude Code schließt stdin des Servers und beendet dann den Prozessbaum des Servers, wenn der Prozess 300 Millisekunden später noch läuft.

Vor v2.1.296 beendete Claude Code unter Windows den Prozessbaum des Servers sofort, ohne zuerst stdin zu schließen oder zu warten.

Option 4: Einen Remote-WebSocket-Server hinzufügen

WebSocket-Server halten eine persistente bidirektionale Verbindung, die sich für Remote-MCP-Server eignet, die Claude unaufgefordert Ereignisse übermitteln. Verwenden Sie HTTP, wenn Ihr Server nur auf Anfragen antwortet, da HTTP OAuth und das Flag claude mcp add --transport unterstützt, während WebSocket beides nicht unterstützt.

Konfigurieren Sie WebSocket-Server in .mcp.json oder mit claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

Der Eintrag type: "ws" akzeptiert dieselben Felder url, headers, headersHelper, timeout und alwaysLoad wie http. Die Authentifizierung erfolgt nur über Header. Übergeben Sie ein statisches Token in headers oder generieren Sie eines beim Verbinden mit headersHelper. Das Flag claude mcp add --transport akzeptiert ws nicht.

Einen Server aus Setupanweisungen hinzufügen, die für einen anderen Client geschrieben wurden

MCP-Server sind nicht spezifisch für Claude Code, daher können die Setupanweisungen eines Servers für Claude Desktop, Cursor oder einen anderen MCP-Client geschrieben sein und keinen claude mcp add-Befehl geben. Um den Server trotzdem hinzuzufügen, suchen Sie in diesen Anweisungen nach einer URL, einem Startbefehl oder einem JSON-Block:

• Eine URL wie https://mcp.example.com/mcp: Der Server ist Remote.
• Ein Startbefehl wie npx -y @example/mcp-server: Der Server wird auf Ihrem Computer ausgeführt.
• Ein mcpServers-JSON-Block: Konfiguration, die für die Einstellungsdatei eines anderen Clients geschrieben wurde.

Jede ist eine der Eingaben, die die vier Optionen in MCP-Server installieren benötigen. Finden Sie die Form, die Sie haben, unten, um sie in den Befehl umzuwandeln, den Claude Code akzeptiert. Jeder Befehl schreibt in lokalen Bereich, es sei denn, Sie fügen --scope project oder --scope user hinzu.

Einen Server aus einer URL hinzufügen

Eine URL bedeutet, dass der Server Remote ist. Für einen https://-Endpunkt fügen Sie ihn mit --transport http hinzu, oder folgen Sie Option 2, wenn die Anweisungen sagen, dass der Endpunkt SSE verwendet. Für einen wss://-Endpunkt verwenden Sie stattdessen Option 4, da --transport ws nicht akzeptiert:

claude mcp add --transport http example https://mcp.example.com/mcp

Wenn die Anweisungen auch einen API-Schlüssel oder Token-Header geben, übergeben Sie ihn mit --header wie in Option 1 gezeigt.

Einen Server aus einem npx-, uvx- oder Binärbefehl hinzufügen

Ein Startbefehl bedeutet, dass der Server als lokaler Stdio-Prozess ausgeführt wird. Platzieren Sie den gesamten Befehl nach --, sodass Claude Code Flags wie -y an den Befehl übergibt, der den Server startet, anstatt sie als seine eigenen Optionen zu lesen. Übergeben Sie alle Umgebungsvariablen, die die Anweisungen anfordern, mit --env, nach dem Servernamen und vor --:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

Option 3 behandelt den ---Trennzeichen vollständig.

Einen Server aus einem mcpServers-JSON-Block hinzufügen

Ein mcpServers-Block, der für einen anderen MCP-Client wie Claude Desktop geschrieben wurde, verwendet den Wrapper-Schlüssel und die Eintragform, die Claude Code liest. Übergeben Sie claude mcp add-json das Objekt in mcpServers, nicht den Wrapper. Zwei Einträge benötigen zuerst eine Reparatur:

• Eine url ohne type: Fügen Sie "type": "http", "type": "sse" oder "type": "ws" hinzu, um dem Endpunkt zu entsprechen. Claude Code liest einen Eintrag ohne type als Stdio-Server, daher schlägt ein url-Eintrag ohne type fehl.
• Ein Schlüssel mit Zeichen außer Buchstaben, Zahlen, Bindestrichen und Unterstrichen: Wählen Sie einen Servernamen, der nur diese Zeichen verwendet. Andernfalls ist der Schlüssel der Servername.

Zum Beispiel wird dieser Block:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

zu diesem Befehl:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

MCP-Server aus JSON-Konfiguration hinzufügen behandelt Shell-Escaping und das Flag --scope für add-json. Um den Server stattdessen mit Ihrem Team zu teilen, fügen Sie --scope project hinzu, oder fügen Sie den Eintrag unter mcpServers in .mcp.json in Ihrem Projektstammverzeichnis hinzu und committen Sie ihn. Projektbereich behandelt, wie Claude Code diese Datei lädt und genehmigt.

Jeder claude mcp add- und claude mcp add-json-Befehl gibt bei Erfolg eine Added ...-Zeile aus. Um zu überprüfen, dass Claude Code verbunden ist, führen Sie claude mcp get <name> aus; Serverstatus behandelt die Statuse, die er anzeigt, und den Genehmigungsschritt für .mcp.json-Server.

Ihre Server verwalten

Nach der Konfiguration können Sie Ihre MCP-Server mit diesen Befehlen verwalten:

# Alle konfigurierten Server auflisten
claude mcp list

# Details für einen bestimmten Server abrufen
claude mcp get notion

# Einen Server entfernen
claude mcp remove notion

# (innerhalb von Claude Code) Serverstatus überprüfen
/mcp

Wenn Sie einen Remote-Server entfernen, löscht Claude Code auch die OAuth-Tokens und die Client-Registrierung, die es für diesen Server gespeichert hat.

Serverstatus

claude mcp add bestätigt ein erfolgreiches Hinzufügen durch Ausgabe einer Added ...-Zeile, was bedeutet, dass die Konfiguration geschrieben wurde. Wenn der Befehl stattdessen eine was not saved-Meldung ausgibt, siehe MCP-Server wurde nicht gespeichert oder entfernt; für eine may not have been saved-Meldung siehe MCP-Server wurde möglicherweise nicht gespeichert oder entfernt.

claude mcp list zeigt neben jedem aufgelisteten Server einen Gesundheitsstatus an, wie ✔ Connected, ! Needs authentication oder ✘ Failed to connect. Ein Fehlerstatus bedeutet, dass Claude Code keine Verbindung zu diesem Server herstellen konnte, nicht dass der List-Befehl fehlgeschlagen ist.

Die Statuse in dieser Liste melden eine Konfigurationsentscheidung statt eines Verbindungsversuchs, daher gibt Claude Code sie aus, ohne sich mit dem Server zu verbinden:

• ⏸ Pending approval (run `claude` to approve): ein projektbezogener Server aus .mcp.json, den Sie noch nicht genehmigt haben. Claude Code zeigt ihn sowohl in claude mcp list als auch in claude mcp get <name> an. Führen Sie claude interaktiv aus, um ihn zu prüfen und zu genehmigen.
• ✘ Rejected (see disabledMcpjsonServers in settings): ein .mcp.json-Server, den ein disabledMcpjsonServers-Eintrag ablehnt. Claude Code zeigt ihn nur in claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): ein Server, den die disabledMcpServers-Liste des Projekts nennt. Claude Code zeigt ihn sowohl in claude mcp list als auch in claude mcp get <name>. Schalten Sie den Server über das /mcp-Panel wieder ein.

Genehmigungen von Projektservern und Workspace-Vertrauen

claude mcp list und claude mcp get lesen .mcp.json-Genehmigungen nur aus Einstellungsdateien, die nicht in das Repository eingecheckt werden, bis Sie dem Workspace vertrauen, indem Sie claude darin ausführen und den Workspace-Vertrauensdialog akzeptieren. Ein geklontes Repository kann seine eigenen Server nicht genehmigen: enableAllProjectMcpServers oder enabledMcpjsonServers, die in die .claude/settings.json des Projekts eingecheckt werden, werden in einem nicht vertrauenswürdigen Ordner ignoriert, und der Server bleibt bei ⏸ Pending approval, statt verbunden und auf seinen Zustand geprüft zu werden.

Genehmigungen aus diesen Quellen gelten weiterhin in einem nicht vertrauenswürdigen Ordner:

• Ihre Benutzer-~/.claude/settings.json
• verwaltete Einstellungen
• Einstellungen, die mit --settings übergeben werden

Claude Code wendet auch Genehmigungen aus einer nicht verfolgten .claude/settings.local.json an, aber es führt git aus, um zu überprüfen, ob die Datei verfolgt wird, und führt diese Überprüfung nur in einem vertrauenswürdigen Ordner durch. In einem Ordner, dem Sie noch nie vertraut haben, wartet Claude Code auf den Vertrauensdialog, bevor die Genehmigungen der Datei angewendet werden, es sei denn, der Ordner ist Ihr eigenes Konfigurationsheim: Ihr Home-Verzeichnis oder ein Verzeichnis, dessen .claude Sie als CLAUDE_CONFIG_DIR gesetzt haben. Vor v2.1.207 wendete Claude Code Genehmigungen aus einer nicht verfolgten .claude/settings.local.json auch in einem Ordner an, dem Sie noch nie vertraut hatten.

Ein disabledMcpjsonServers-Eintrag in einer beliebigen Einstellungsdatei lehnt den Server weiterhin ab.

Serverstatus-Detail

In /mcp, einschließlich des Menüs eines Servers dort, und im /plugin-Manager kann ein Remote-HTTP- oder SSE-Server, den Sie zuvor verwendet haben, einen cached-Status wie cached 2h ago · connects on first use · 5 tools anzeigen. Claude Code hat die Werkzeugliste des Servers aus seinem Erkennungs-Cache geladen, der in einer vorherigen Sitzung gespeichert wurde, anstatt beim Start zu verbinden, und Claude Code verbindet den Server das erste Mal, wenn Claude eines der Werkzeuge des Servers aufruft. Die Werkzeuge sind ab Ihrer ersten Nachricht verfügbar, daher müssen Sie nichts tun. Der Erkennungs-Cache und sein cached-Status erfordern Claude Code v2.1.221 oder später.

Der Erkennungs-Cache ist standardmäßig deaktiviert, es sei denn, ein schrittweiser Rollout hat ihn für Ihr Konto aktiviert. Setzen Sie MCP_DISCOVERY_CACHE=1, um ihn einzuschalten, oder 0, um ihn deaktiviert zu halten, auch wenn der Rollout ihn aktiviert hat. Vor v2.1.238 war der Cache standardmäßig aktiviert.

Wenn Sie Disable oder Clear authentication aus dem Menü eines Servers in /mcp auswählen, verwirft Claude Code auch den Cache-Eintrag dieses Servers. Reconnect verwirft ihn auch auf einem verbundenen oder fehlgeschlagenen Server; auf einem cached-Server verbindet Reconnect den Server jetzt und behält den Eintrag. Das nächste Mal, wenn Claude Code sich mit dem Server verbindet, nachdem der Eintrag verworfen wurde, ruft es die Werkzeugliste vom Server ab, anstatt sie aus dem Cache zu holen.

Wenn der Status eines Servers ✘ Failed to connect ist, hängt claude mcp list das Fehlerdetail an diese Statuszeile an, und claude mcp get <name> zeigt es auf einer Issue:-Zeile: der HTTP-Status oder Fehlercode, plus jeder Fehlertext, den der Server zurückgegeben hat. Die Detailansicht des Servers in /mcp enthält denselben vom Server gemeldeten Text in seiner Issue:-Zeile. Claude Code redigiert anmeldungsähnlichen Text aus diesem Detail und enthält niemals die erweiterte Server-URL, die Geheimnisse tragen kann. Claude Code hängt kein Detail an einen ✘ Connection error-Status an, da der Ausnahmetext, den es dort ausgeben würde, diese URL einbetten kann. Vor v2.1.219 zeigten beide Befehle nur den bloßen Fehlerstatus ohne Statuscode oder Fehlertext des Servers.

Wenn Sie die Authentifizierung von /mcp aus abschließen und die Verbindung immer noch mit einem HTTP-Status oder einem Transportfehlercode fehlschlägt, fügt Claude Code diesen Code und den Ursprung der Server-URL zur Meldung hinzu, die es nach dem Versuch ausgibt. Der Ursprung ist das Schema und der Host, plus der Port, wenn die URL einen nennt, wie https://mcp.example.com.

• Der Pfad und die Abfrage erscheinen niemals in dieser Meldung.
• Für einen Server im lokalen, Projekt- oder Benutzer-Bereich oder in verwalteter MCP-Konfiguration zeigt der Ursprung den Host wie in dieser Konfiguration geschrieben, daher wird eine ${VAR}-Referenz im Host in der Meldung nicht erweitert.
• Bei einem Fehler ohne Status oder Fehlercode zeigt Claude Code den Fehlertext ohne den Ursprung.

Ein Remote-Server, dessen Konfiguration eine leere url hat, wird in /mcp, in claude mcp list und im /plugin-Manager als not configured angezeigt, und Claude Code versucht nicht, sich damit zu verbinden. Ein Plugin kann einen Platzhalter-Eintrag wie diesen für einen Connector enthalten, den Sie später konfigurieren, sodass Claude Code ihn nicht als Fehler oder Setup-Problem meldet. Die Detailansicht des Servers in /mcp zeigt No URL configured for this server; setzen Sie die url des Eintrags, um ihn zu verbinden.

Konfigurationswarnungen

Claude Code warnt vor den folgenden Konfigurationsproblemen. Jeder Eintrag sagt, was Claude Code überprüft und wie die Warnung beseitigt wird:

• Versteckte Leerzeichen: Claude Code warnt, wenn ein MCP-Konfigurationswert versteckte führende oder nachfolgende Leerzeichen trägt, die oft vom Einfügen eines Tokens mit einem nachfolgenden Zeilenumbruch stammen. Claude Code überprüft command, url, jeden args-Eintrag und die Werte und Schlüsselnamen unter env und headers. Claude Code zeigt die Warnung in der claude mcp list-Ausgabe und in /mcp an und nennt die betroffenen Felder, ohne ihre Werte auszugeben, zum Beispiel Leading or trailing whitespace in: headers.Authorization. Claude Code trimmt die Leerzeichen nicht und verwendet die Werte genau wie geschrieben, daher bearbeiten Sie die Konfiguration, um sie zu entfernen.
• Gleicher Name in mehr als einem Bereich: Wenn Sie denselben Servernamen in mehr als einem Bereich mit verschiedenen Endpunkten definieren, warnt Claude Code vor dem Konflikt in der claude mcp list-Ausgabe und in /mcp. Claude Code speichert OAuth-Anmeldungen pro Endpunkt, daher müssen Sie sich, wenn Sie die Definition authentifizieren, die in einem Projekt geladen wird, in einem Projekt, in dem eine andere Definition geladen wird, immer noch separat anmelden. Behalten Sie den Endpunkt, den Sie möchten, und entfernen Sie die anderen mit claude mcp remove <name> --scope <scope>. In der Warnung zitiert Claude Code den Endpunkt jedes Bereichs wie in Ihrer Konfiguration geschrieben, mit ${VAR}-Referenzen nicht erweitert, daher zeigt es niemals einen aufgelösten Wert wie einen API-Schlüssel.
• Reservierte Namen: Claude Code reserviert die Namen seiner integrierten Server, einschließlich workspace, claude-in-chrome, computer-use, Claude Preview und Claude Browser. Wenn Ihre Konfiguration einen Server mit einem reservierten Namen definiert, überspringt Claude Code ihn beim Laden und zeigt eine Warnung an, die Sie auffordert, ihn umzubenennen. claude mcp add lehnt einen reservierten Namen mit einem Fehler ab. Claude Preview und Claude Browser benennen beide den integrierten Server, den das Vorschau-Panel der Claude Code Desktop-App verwendet.
• Fehlende Umgebungsvariable: Wenn eine ${VAR}-Referenz in der Konfiguration eines Servers eine Variable nennt, die nicht gesetzt ist und keinen :-default hat, warnt Claude Code in der claude mcp list-Ausgabe und in /mcp, nennt die Variable und lädt den Server immer noch mit dem ${VAR}-Text nicht erweitert. Setzen Sie die Variable oder fügen Sie einen ${VAR:-default}-Fallback hinzu. In der url und headers eines Remote-Servers lesen einige Anmeldungsvariablen stattdessen als leer, ohne Warnung.

Werkzeugverfügbarkeit

Das /mcp-Panel zeigt die Werkzeuganzahl neben jedem verbundenen Server und kennzeichnet Server, die die Werkzeugfähigkeit ankündigen, aber keine Werkzeuge bereitstellen.

Wenn Ihre Anfrage Werkzeuge von einem Server benötigt, der sich noch im Hintergrund verbindet, wartet Claude auf diesen Server, bevor er fortfährt. Wie das Warten geschieht, hängt von Ihrer Konfiguration ab:

• Mit Werkzeugsuche, der Standard: Das Warten geschieht innerhalb des ToolSearch-Aufrufs.
• Ohne Werkzeugsuche: Claude verwendet stattdessen das WaitForMcpServers-Werkzeug. Konfigurationen ohne Werkzeugsuche umfassen ENABLE_TOOL_SEARCH=false und ein Modell, das älter als Claude Opus 4.5, Claude Sonnet 4.5 und Claude Haiku 4.5 ist, auf Google Clouds Agent Platform. Für ein ANTHROPIC_BASE_URL-Gateway siehe Werkzeugsuche über ein LLM-Gateway.
• Bei einer Microsoft Foundry-Bereitstellung auf Azure gehostet: Claude startet auf dem Werkzeugsuche-Pfad statt mit WaitForMcpServers, da Claude Code die serverseitige Ablehnung der Bereitstellung nur von der API entdeckt. Nachdem Claude Code diese Bereitstellung auf vorausgehendes Laden umschaltet, werden Werkzeuge von einem Server, der seinen Verbindungsaufbau abschließt, bei Claudes nächster Anfrage verfügbar.

Mit aktivierter Werkzeugsuche, wenn ein Server seinen Verbindungsaufbau abschließt, während Claude arbeitet, listet Claude Code die Werkzeugnamen des Servers bei Claudes nächster Anfrage im selben Turn auf. Claude kann dann diese Werkzeuge suchen und aufrufen, ohne auf Ihre nächste Nachricht zu warten.

Nachdem Sie eine Sitzung fortgesetzt haben, kann Claude ein Tool aus der gespeicherten Konversation aufrufen, während der MCP-Server des Tools noch eine Verbindung herstellt. Während der Server seinen ersten Verbindungsversuch unternimmt, hält Claude Code den Aufruf bis zu 10 Sekunden zurück und führt ihn aus, sobald das Tool verfügbar ist. Wenn der Server nicht rechtzeitig eine Verbindung herstellt oder es bereits nach einem fehlgeschlagenen Versuch erneut versucht, schlägt der Aufruf mit dem Tool-Fehler No such tool available fehl.

Einen Server deaktivieren, ohne ihn zu entfernen

Schalten Sie einen Server im /mcp-Panel aus, um Claude Code daran zu hindern, sich damit zu verbinden, ohne seine Konfiguration zu verlieren. Claude Code listet den Server immer noch in /mcp auf, gekennzeichnet als deaktiviert.

Wenn Sie einen Server umschalten, zeichnet Claude Code Ihre Wahl pro Projekt in ~/.claude.json in einer von zwei Listen auf, die disjunkte Sätze von Servern abdecken:

• disabledMcpServers: eine Opt-out-Liste für benutzerkonfigurierte Server, Plugin-Server, Server, die Ihre Organisation durch verwaltete Einstellungen bereitstellt, die claude.ai-Connectoren, die Claude Code selbst abruft, und integrierte Server, die standardmäßig aktiviert sind. Claude Code verbindet sich nicht mit einem Server, den Sie hier auflisten. Wenn Sie einen claude.ai-Connector mit dem pro-Projekt-/mcp-Umschalter deaktivieren, der in claude.ai-Connectoren deaktivieren beschrieben ist, schreibt Claude Code ihn unter seinem Anzeigenamen in diese Liste, zum Beispiel claude.ai Slack.
• enabledMcpServers: eine Opt-in-Liste für integrierte Server, die standardmäßig deaktiviert sind, wie computer-use. Claude Code verbindet sich mit einem standardmäßig deaktivierten Server nur, wenn Sie ihn hier auflisten.

Claude Code konsultiert genau eine der beiden Listen für jeden Server, daher überschreibt keine Liste die andere. Wenn Sie einen regulären Server zu enabledMcpServers hinzufügen oder einen standardmäßig deaktivierten integrierten Server zu disabledMcpServers, ignoriert Claude Code den Eintrag.

disabledMcpServers und enabledMcpServers sind nicht verwandt mit enabledMcpjsonServers und disabledMcpjsonServers, die die Genehmigung von Servern steuern, die in der .mcp.json-Datei eines Projekts definiert sind.

MCP-Client-Runtimes

Claude Code verbindet sich mit MCP-Servern über eine von zwei Client-Runtimes. Die v1-Runtime basiert auf MCP TypeScript SDK 1.x. Die v2-Runtime ist derselbe Code auf MCP TypeScript SDK 2.0, das MCP-Protokollrevision 2026-07-28 hinzufügt. Der Rest dieser Seite gilt für beide Runtimes, außer wo ein Abschnitt die v2-Runtime nennt.

Claude Code wählt jedes Mal, wenn Sie es starten, eine Runtime aus und behält sie bis zum Beenden. In Sitzungen, in denen es Feature-Flags abruft, verwendet es die v2-Runtime auf Claude Code v2.1.232 oder später.

In den Sitzungen, in denen es keine Feature-Flags abruft, verwendet Claude Code die v2-Runtime standardmäßig auf Claude Code v2.1.274 oder später:

• Sitzungen auf Amazon Bedrock, Claude Platform auf AWS, Google Clouds Agent Platform oder Microsoft Foundry, es sei denn, eine Host-Plattform, die Claude Code einbettet, setzt CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST
• Sitzungen, die sich über ein Claude-Apps-Gateway anmelden
• Sitzungen, in denen Sie Telemetrie oder Feature-Flag-Abruf deaktivieren, zum Beispiel mit DISABLE_TELEMETRY

Auf v2 gilt außerdem für Claude Code:

• Es fragt HTTP-, Stdio- und claude.ai-Konnektor-Server, ob sie die neuere Revision unterstützen, und verwendet sie mit denen, die dies tun. Dazu gehören die Konnektoren von Cloud- und Remote Control-Sitzungen. Es verbindet sich mit jedem anderen Server wie v1.
• Es empfängt list_changed-Benachrichtigungen von Servern auf der neueren Revision über einen Stream, den es offen hält.
• Es registriert keinen Channel-Server, der sich auf der neueren Revision verbindet, da diese Revision keine Channel-Nachrichten tragen kann.
• Es lässt eine MCP-OAuth-Anmeldung fehlschlagen, deren Autorisierungsantwort einen unerwarteten Aussteller nennt.
• Es sendet MCP-OAuth-Anmeldedaten nur an einen Token-Endpunkt, der über HTTPS oder bei localhost, 127.0.0.1 oder ::1 bereitgestellt wird. Die Anmeldung schlägt für einen Server fehl, dessen Token-Endpunkt einfaches http:// irgendwo anders ist, wie ein Gerät in Ihrem lokalen Netzwerk. Siehe Refusing to send credentials to non-https token endpoint.

Anthropic kann einen bestimmten Server mit einem Feature-Flag, das Claude Code abruft, auf dem früheren Protokoll halten oder aus diesem Stream entfernen.

Um die Runtime selbst auszuwählen, setzen Sie MCP_SDK_GENERATION auf v1 oder v2. Um zu entscheiden, ob Claude Code fragt, setzen Sie MCP_PROTOCOL_NEGOTIATION auf auto oder legacy.

Dynamische Werkzeugaktualisierungen

Ein MCP-Server kann die Tools, Prompts oder Ressourcen, die er anbietet, während der Verbindung ändern und eine list_changed-Benachrichtigung senden. Wenn eine solche Benachrichtigung eintrifft:

• In einer interaktiven Terminal-Sitzung ruft Claude Code die aktualisierte Liste von diesem Server ab, sodass Sie ihn nicht erneut verbinden müssen.
• Im nicht interaktiven Modus mit dem Flag -p und im Agent SDK aktualisiert Claude Code bei diesen Benachrichtigungen nur die Tool-Liste.

Wenn eine Aktualisierungsanfrage fehlschlägt, behält Claude Code die zuvor entdeckten Werkzeuge, Prompts und Ressourcen des Servers, bis eine spätere Aktualisierung erfolgreich ist.

Benachrichtigungsströme auf der v2-Runtime

Auf der v2-Runtime empfängt Claude Code list_changed-Benachrichtigungen von einem Server auf der neueren Protokollrevision über einen Stream, den es offen hält. Wenn der Stream schließt, öffnet Claude Code ihn erneut, mit zwei Grenzen:

• Der Stream schließt innerhalb von 10 Sekunden erneut: Claude Code öffnet ihn bis zu dreimal erneut, dann stoppt es für diese Verbindung.
• Der Stream bleibt länger als 10 Sekunden offen und schließt dann, wie es Streams zu serverlosen Hosts häufig tun: Nach fünf Wiederöffnungen in einer Stunde wartet Claude Code etwa sechs Stunden vor der nächsten.

Bis der Stream erneut öffnet, behalten Sie die zuletzt abgerufenen Werkzeuge, Prompts und Ressourcen des Servers. Um seine Änderungen schneller zu erkennen, verbinden Sie den Server von /mcp erneut.

Automatische Wiederverbindung

Claude Code verbindet einen Remote-Server erneut, der während einer Sitzung abbricht, und versucht die erste Verbindung eines HTTP- oder SSE-Servers nach einem vorübergehenden Fehler erneut. Für einen Stdio-Server siehe Stdio-Server, die beendet werden oder nicht starten.

Mitten in der Sitzung abbrechende Remote-Server

Claude Code versucht zunächst, einen abgebrochenen Remote-Server bis zu fünfmal mit exponentiellem Backoff erneut zu verbinden, beginnend mit einer Verzögerung von einer Sekunde, die sich jedes Mal verdoppelt:

• In einer interaktiven Sitzung: /mcp zeigt den Server als ausstehend an, während Claude Code erneut verbindet. Nach fünf fehlgeschlagenen Versuchen markiert Claude Code den Server als fehlgeschlagen oder als Authentifizierung erforderlich, wenn der Server erneut autorisiert werden muss. Wenn es den Server als fehlgeschlagen markiert, sehen Sie eine MCP server "<name>" disconnected · open /mcp to reconnect-Benachrichtigung. Sie können es manuell von /mcp aus erneut versuchen.
• In claude -p-Läufen und Agent SDK-Sitzungen: Claude Code unternimmt dieselben fünf Versuche, ohne /mcp-Panel, um sie anzuzeigen. Wenn alle fünf fehlschlagen, läuft der Lauf ohne die Tools des Servers weiter:
  • Nach einem vorübergehenden Fehler, etwa einer 5xx-Antwort oder einem Timeout: Claude Code versucht es bei einem HTTP- oder SSE-Server im Hintergrund weiter. Die Wiederholungsversuche dauern bis zu etwa einer halben Stunde, und die Tools des Servers werden wieder verfügbar, wenn einer davon eine Verbindung herstellt. Bis dahin meldet eine Agent SDK-Sitzung den Status failed, und Ihr Code kann den Server erneut verbinden. Um ihn in claude -p erneut zu verbinden, starten Sie den Lauf neu.
  • Wenn der Server eine erneute Anmeldung von Ihnen erfordert: Claude Code beendet die Wiederholungsversuche, und eine Agent SDK-Sitzung meldet den Status des Servers als needs-auth. Melden Sie sich in Ihrer Shell mit claude mcp login <name> an. Starten Sie dann den Lauf neu oder verbinden Sie den Server in einer Agent SDK-Sitzung stattdessen erneut.

Fehlgeschlagene erste Verbindungen

Wenn die erste Verbindung eines HTTP- oder SSE-Servers mit einem vorübergehenden Fehler fehlschlägt, wie einer 5xx-Antwort, einer verweigerten Verbindung oder einem Timeout, versucht Claude Code es bis zu dreimal erneut. Wenn die Verbindung immer noch fehlschlägt, markiert Claude Code den Server als fehlgeschlagen.

Diese Wiederholungsversuche gelten in folgenden Fällen nicht:

• Die erste Verbindung eines Stdio-Servers. Um es erneut zu versuchen, siehe Stdio-Server, die beendet werden oder nicht starten
• Die erste Verbindung eines WebSocket-Servers. Um es in einer interaktiven Terminal-Sitzung erneut zu versuchen, wählen Sie im Menü des Servers in /mcp Reconnect aus
• Ein Authentifizierungs- oder Not-Found-Fehler, da er eine Konfigurationsänderung erfordert, um ihn zu beheben. Wenn ein headersHelper die einzige Quelle des Authorization-Headers des Servers ist, versucht Claude Code einen Authentifizierungsfehler trotzdem erneut, da es den Helper bei jedem Versuch erneut ausführt und frische Anmeldedaten abholen kann

Stdio-Server, die beendet werden oder nicht starten

Um einen Stdio-Server erneut zu starten, lesen Sie die Spalte, die dem entspricht, was mit ihm passiert ist. Ihre Zeile finden Sie anhand dessen, wie Sie Claude Code ausführen: in einer interaktiven Sitzung, in einem claude -p-Lauf oder in einer Agent SDK-Sitzung.

Fehlgeschlagene Erkennungsanfragen

Nachdem sich ein Server verbindet, sendet Claude Code ihm Anfragen zur Fähigkeitserkennung wie tools/list, prompts/list und resources/list. Claude Code versucht diese Anfragen bis zu dreimal mit kurzem Backoff nach einem vorübergehenden Netzwerk- oder Serverfehler erneut. Es versucht Authentifizierungsfehler, 4xx-Antworten oder Anfrage-Timeouts nicht erneut.

Fehlgeschlagene Server selbst erneut versuchen

Um alle Server erneut zu versuchen, die fehlgeschlagen sind oder eine Authentifizierung benötigen, führen Sie in einer interaktiven Terminal-Sitzung am Claude Code-Prompt /mcp reconnect all aus. Dies erfordert Claude Code v2.1.284 oder neuer. Ältere Versionen geben MCP server "all" not found aus.

Wie Claude erfährt, dass ein Server fehlgeschlagen ist

Ob Claude Code Claude über einen konfigurierten Server informiert, der keine Verbindung hergestellt hat, hängt von der Werkzeugsuche ab, die standardmäßig aktiviert ist:

• Mit Werkzeugsuche teilt Claude Code Claude mit, welcher Server fehlgeschlagen ist und welchen Verbindungsfehler er hatte, daher meldet Claude den Verbindungsfehler in seiner Antwort. Claude Code nimmt dieselben Informationen in ToolSearch-Ergebnisse auf, die kein passendes Werkzeug finden.
• In jeder Konfiguration ohne Werkzeugsuche meldet Claude Code fehlgeschlagene Serververbindungen nicht an Claude.

Nachrichten mit Channels pushen

Ein MCP-Server kann auch Nachrichten direkt in Ihre Sitzung pushen, damit Claude auf externe Ereignisse wie CI-Ergebnisse, Überwachungswarnungen oder Chat-Nachrichten reagieren kann. Um dies zu aktivieren, deklariert Ihr Server die claude/channel-Fähigkeit und Sie aktivieren sie mit dem Flag --channels beim Start. Siehe Channels, um einen offiziell unterstützten Channel zu verwenden, oder Channels-Referenz, um Ihren eigenen zu erstellen.

Auf der v2-Runtime kann ein Channel-Server, der MCP-Protokollrevision 2026-07-28 aushandelt, keine Channel-Nachrichten liefern, daher registriert Claude Code ihn nicht als Channel. Ein Channel-Server, der diese Revision nicht unterstützt, verbindet sich über den früheren Handshake und registriert sich wie bisher.

Claude Code fragt Stdio-Server standardmäßig nach dieser Revision. Um einen Stdio-Channel-Server auf dem früheren Handshake zu halten, setzen Sie MCP_PROTOCOL_NEGOTIATION auf legacy, wodurch alle Server darauf bleiben.

[!TIP]

Tipps:

• Verwenden Sie das Flag -s oder --scope, um anzugeben, wo die Konfiguration gespeichert wird:
  • local (Standard): nur für Sie im aktuellen Projekt verfügbar
  • project: geteilt mit allen im Projekt über die .mcp.json-Datei
  • user: für Sie über alle Projekte verfügbar
• Setzen Sie Umgebungsvariablen mit den Flags -e oder --env (zum Beispiel -e KEY=value)
• Die Flags --transport und --header akzeptieren auch die Kurzformen -t und -H
• Konfigurieren Sie den MCP-Server-Start-Timeout mit der Umgebungsvariable MCP_TIMEOUT (zum Beispiel setzt MCP_TIMEOUT=10000 claude einen 10-Sekunden-Timeout)
• Setzen Sie einen Pro-Server-Timeout für die Werkzeugausführung, indem Sie ein timeout-Feld in Millisekunden zum .mcp.json-Eintrag dieses Servers hinzufügen, zum Beispiel "timeout": 600000 für zehn Minuten. Dies überschreibt die Umgebungsvariable MCP_TOOL_TIMEOUT nur für diesen Server
• Claude Code zeigt eine Warnung an, wenn die MCP-Werkzeugausgabe 10.000 Token überschreitet, und begrenzt die Ausgabe standardmäßig auf 25.000 Token. Um das Token-Limit zu ändern, setzen Sie die Umgebungsvariable MAX_MCP_OUTPUT_TOKENS, zum Beispiel MAX_MCP_OUTPUT_TOKENS=50000. Die Warnschwelle ist fest. Sofern der Server das eigene Limit eines Tools nicht anhebt, werden erfolgreiche Textergebnisse mit mehr als 50.000 Zeichen unabhängig von dieser Variable in einer Datei gespeichert. Siehe MCP-Ausgabegrenzen und Warnungen
• Verwenden Sie /mcp, um sich bei Remote-Servern zu authentifizieren, die OAuth 2.0-Authentifizierung erfordern

Zeitlimits für MCP-Tool-Aufrufe

Um zu begrenzen, wie lange ein MCP-Tool-Aufruf laufen darf:

• Pro Server: Fügen Sie dem Konfigurationseintrag dieses Servers ein Feld timeout in Millisekunden hinzu
• Serverübergreifend: Setzen Sie MCP_TOOL_TIMEOUT

Der Pro-Server-timeout ist eine harte Wanduhr-Grenze pro Werkzeugaufruf, und Fortschrittsbenachrichtigungen vom Server verlängern ihn nicht. Werte unter 1000 werden ignoriert und fallen auf MCP_TOOL_TIMEOUT zurück oder auf dessen Standard von etwa 28 Stunden, wenn diese Variable nicht gesetzt ist. Für einen HTTP-, SSE- oder claude.ai-Connector-Server gibt es auch einen zweiten Pro-Anfrage-Timer, der jede Anfrage bis zum ersten Antwortbyte des Servers abdeckt. Claude Code setzt diesen Timer auf den größten von drei Werten: 60 Sekunden, den Werkzeug-Timeout, der für den Server gilt, und MCP_TIMEOUT. Der 28-Stunden-Standard eines nicht gesetzten MCP_TOOL_TIMEOUT geht nicht in diesen Vergleich ein, und ein Wert unter 60 Sekunden verkürzt den Timer nicht. Stdio- und WebSocket-Server haben keinen Pro-Anfrage-Timer.

Ein Pro-Server-timeout von mindestens 1000 fungiert auch als Untergrenze für den unten beschriebenen Idle-Timeout: Claude Code bricht die Werkzeugaufrufe dieses Servers wegen Inaktivität nie früher als nach dem Pro-Server-timeout ab.

Ein Werkzeugaufruf an einen MCP-Server, der für das Idle-Fenster keine Antwort und keine Fortschrittsbenachrichtigung sendet, bricht mit einem Fehler ab, anstatt auf die Wanduhr-Grenze zu warten. Der Idle-Timeout gilt für jeden Servertyp außer IDE-Servern und SDK-In-Process-Servern. Das Idle-Fenster beträgt standardmäßig fünf Minuten für HTTP-, SSE-, WebSocket- und claude.ai-Connector-Server und 30 Minuten für Stdio-Server.

Setzen Sie die Umgebungsvariable CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in Millisekunden, um das Idle-Fenster zu ändern, oder setzen Sie sie auf 0, um die Überprüfung zu deaktivieren.

Diese Timeouts begrenzen, wie lange ein Aufruf laufen kann, nicht immer, wie lange er die Sitzung blockiert: Ein Aufruf in der Hauptkonversation, der länger als zwei Minuten läuft, wird zuerst zu einer Hintergrundaufgabe. Siehe Automatisches Backgrounding von langen Werkzeugaufrufen.

Automatisches Backgrounding von langen Werkzeugaufrufen

Wenn die Detailansicht eines Hintergrundaufrufs in /tasks runs on the server; survives exiting this session anzeigt, siehe MCP-Tasks, die auf dem Server laufen.

Ein MCP-Werkzeugaufruf in der Hauptkonversation, der nach zwei Minuten noch läuft, wird zu einer Hintergrundaufgabe, statt die Sitzung zu blockieren. Claude erhält die Aufgaben-ID sofort und arbeitet weiter, und das Ergebnis kommt als Aufgabenbenachrichtigung, wenn der Aufruf abgeschlossen ist.

Die Aufgabe erscheint in /tasks, wo Sie sie auch stoppen können, und sie überlebt das Beenden der Sitzung nicht. Der Eintrag der Aufgabe zeigt den neuesten Fortschritt, den der Server gemeldet hat. Wenn Sie die Aufgabe stoppen, bricht Claude Code den Aufruf ab und teilt Claude mit, dass kein Ergebnis kommt. Das Stoppen garantiert nicht, dass der Server stoppt: Er hat möglicherweise bereits einen Teil der Arbeit erledigt oder schließt sie trotzdem ab.

Die Pro-Aufruf-Grenzen gelten weiterhin, während der Aufruf im Hintergrund läuft: die Wanduhr-Grenze, die durch den Pro-Server-timeout oder MCP_TOOL_TIMEOUT gesetzt wird, und der Idle-Timeout, der durch CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT gesetzt wird.

So ändern oder deaktivieren Sie das automatische Verschieben in den Hintergrund:

• Setzen Sie die Umgebungsvariable CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS in Millisekunden, um den Schwellenwert zu ändern, oder setzen Sie sie auf 0, um das automatische Verschieben auszuschalten. Mit 0 wartet Claude in einer interaktiven Sitzung außerdem auf MCP-Tasks
• Setzen Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1, wodurch es zusammen mit Hintergrundbefehlen und Hintergrund-Subagenten ausgeschaltet wird

Einige Aufrufe werden nie in den Hintergrund verschoben:

• Aufrufe von Subagenten; Claude Code verschiebt nur Aufrufe der Hauptkonversation in den Hintergrund
• Aufrufe an IDE-Server
• Aufrufe im nicht interaktiven Modus, es sei denn, CLAUDE_AUTO_BACKGROUND_TASKS ist auf 1 gesetzt, da ein One-Shot-Lauf enden kann, bevor das Ergebnis ankommt

Ein Aufruf, der auf einen offenen Elicitation-Dialog wartet, wird nicht in den Hintergrund verschoben, solange der Dialog offen ist; der Server wartet auf Ihre Eingabe und ist nicht langsam, daher schiebt Claude Code die Verschiebung auf, bis der Dialog geschlossen wird.

MCP-Tasks, die auf dem Server laufen

Ein MCP-Task ist ein langer Auftrag, etwa ein Berichtsexport oder ein Build, den ein MCP-Server selbst mit der MCP-Tasks-Erweiterung ausführt. Der Tool-Aufruf von Claude kehrt zurück, sobald der Server den Auftrag annimmt, sodass Claude weiterarbeitet, sofern Sie Claude nicht warten lassen. Wenn der Auftrag endet, vermerkt das Transkript dies, und Claude erhält das Ergebnis. Fragen Sie Claude danach.

In der Zwischenzeit zeigt die Fußzeile eine Anzahl wie 1 MCP task, und Claude Code verfolgt den Task, indem es seinen Status beim Server abfragt. Ein Task auf einem Remote-Server läuft nach dem Beenden weiter. Um ihn erneut zu verfolgen, setzen Sie dieselbe Sitzung fort.

[!NOTE]

MCP-Tasks sind in der Claude Code CLI als öffentliche Beta verfügbar und erfordern Claude Code v2.1.304 oder höher. Was ein Aufruf benötigt, um zu einem MCP-Task zu werden listet die Sitzungen und Server auf, die sie erhalten.

Einen MCP-Task stoppen oder sein Ergebnis abrufen

Um einen laufenden Task zu stoppen, wählen Sie ihn in /tasks aus und drücken Sie x, oder bitten Sie Claude darum. Claude Code hört auf, den Task zu verfolgen, und bittet den Server, ihn abzubrechen, wobei der Server ihn dennoch abschließen kann. Verbinden Sie einen getrennten Server zuerst über /mcp neu, sonst wird keine Abbruchanfrage gesendet, und Claude Code vergisst den Task und kann ihn nicht erneut verfolgen. Das Drücken von Esc stoppt keine Hintergrundaufgabe.

Wenn der Task endet, erscheint eine Zeile wie diese im Transkript:

MCP task <server task id> (<server>/<tool>) completed.

Das Ergebnis geht an Claude, nicht in das Transkript. Fragen Sie Claude also danach. Wenn Claude untätig ist, wenn das Ergebnis eintrifft, beginnt Claude unaufgefordert damit.

Eine Frage eines MCP-Tasks beantworten

Ein laufender Task kann einen Elicitation-Dialog öffnen, um Sie um eine Eingabe zu bitten. Solange /tasks geöffnet ist, bleibt der Dialog verborgen. Schließen Sie daher /tasks, um zu antworten. Ablehnen oder das Drücken von Esc ist eine Antwort an den Server, der dann entscheidet, ob der Task weiterläuft.

In einer nicht interaktiven Sitzung bittet Claude Code den Server, einen Task abzubrechen, der eine Eingabe anfordert, ohne Ihre Elicitation-Hooks auszuführen oder den onElicitation-Callback des Agent SDK aufzurufen.

Beenden, Leeren oder Fortsetzen, während ein MCP-Task läuft

Ein Task auf einem Remote-Server läuft nach dem Beenden weiter. Der Prozess eines stdio-Servers stoppt, wenn Claude Code beendet wird, obwohl seine Tasks in /tasks runs on the server; survives exiting this session anzeigen. Sofern die Dokumentation dieses Servers nicht angibt, dass die Arbeit den Prozess überdauert, lassen Sie diese Tasks abschließen oder stoppen Sie sie zuerst in /tasks.

Was ein Aufruf benötigt, um zu einem MCP-Task zu werden

Ein Tool-Aufruf wird nur dann zu einem MCP-Task, wenn alle diese Bedingungen erfüllt sind:

• Der Server unterstützt Tasks
• Der Server ist ein HTTP-, stdio- oder claude.ai-Konnektor-Server, der über die Protokollrevision 2026-07-28 verbunden ist. Das Setzen von MCP_SDK_GENERATION=v1 oder MCP_PROTOCOL_NEGOTIATION=legacy schließt dies aus
• Die Sitzung ruft Feature-Flags ab, also nicht bei einem Drittanbieter wie Amazon Bedrock und nicht bei ausgeschalteter Telemetrie oder ausgeschaltetem Abruf von Flags
• Anthropic hat MCP-Tasks für Ihre Art von Sitzung eingeschaltet. Ab v2.1.304 umfasst das Terminal-CLI-Sitzungen, Agent SDK-Sitzungen und GitHub Actions-Ausführungen. Andere Oberflächen wie die VS Code-Erweiterung und die Desktop-App haben keine MCP-Tasks
• Der Aufruf stammt aus der Hauptkonversation, nicht von einem Subagenten
• Entweder ist die Sitzung interaktiv, oder eine Agent SDK-Sitzung bzw. eine claude -p-Ausführung, die --input-format stream-json liest, hat:
  • CLAUDE_AUTO_BACKGROUND_TASKS auf 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND nicht auf 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS nicht auf 0

Jeder andere Aufruf ist ein gewöhnlicher Tool-Aufruf, und Automatisches Verschieben langer Tool-Aufrufe in den Hintergrund beschreibt, welche davon in den Hintergrund verschoben werden.

Halten Sie die Eingabe einer Agent SDK- oder stream-json-Sitzung offen, da die Ausführung nach dem Schließen der Eingabe nicht auf MCP-Tasks wartet. Eine einmalige claude -p "<prompt>"-Ausführung erhält keine MCP-Tasks.

Statusmeldungen zu einem MCP-Task

Diese Meldungen im /tasks-Eintrag eines Tasks oder in seiner abschließenden Transkriptzeile bedeuten, dass Claude Code den Server oder den Task nicht erreichen kann. Solange eine davon in /tasks angezeigt wird, kann der Auftrag noch laufen: Claude Code lässt ihn in Ruhe und prüft weiter. Die 300s- und Konfigurationsmeldungen bleiben am Eintrag stehen, auch nachdem der Kontakt wiederhergestellt ist.

Zeitlimits für MCP-Tasks

Standardmäßig hat ein Task im Hintergrund kein Zeitlimit von Claude Code. Die Zeitlimits für Tool-Aufrufe, einschließlich des Echtzeitlimits und des Leerlauf-Timeouts, gelten, bis der Server den Aufruf mit dem Task beantwortet. Wenn Sie Claude warten lassen, gelten sie für den gesamten Task. Beantwortete Statusabfragen zählen als Aktivität für den Leerlauf-Timeout.

Claude auf das Ergebnis eines MCP-Tasks warten lassen

Damit Claude in einer interaktiven Sitzung auf das Ergebnis eines Tasks wartet, setzen Sie eine von zwei Umgebungsvariablen, zum Beispiel im env-Block von settings.json:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS auf 0 gesetzt: Claude wartet bei jedem MCP-Tool-Aufruf, bis der Aufruf endet
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND auf 1 gesetzt: Claude wartet auf das Ergebnis eines Tasks. Solange das automatische Verschieben in den Hintergrund eingeschaltet ist, verschiebt es den Aufruf standardmäßig nach zwei Minuten, sodass kurze Tasks an Ort und Stelle abgeschlossen werden und lange Sie nicht blockieren. Der verschobene Aufruf ist ein gewöhnlicher Hintergrundaufruf und kein MCP-Task. Er überdauert das Beenden der Sitzung nicht

Während Claude wartet, beendet das Drücken von Esc oder das Erreichen des Echtzeitlimits oder Leerlauf-Timeouts den Aufruf, und Claude Code bittet den Server, den Task abzubrechen.

Wenn Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1 setzen oder im Bare-Modus starten, lässt das allein Claude nicht auf MCP-Tasks warten. Dieses Beispiel setzt CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS auf 0, sodass Claude bei jedem MCP-Tool-Aufruf wartet:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

MCP-Tasks für Serverautoren

Wenn Sie einen MCP-Server entwickeln, können Sie ein lang laufendes tools/call mit einem Task beantworten. Die MCP-Tasks-Erweiterung definiert die Nachrichten, die Sie senden. Bei einer Verbindung über die Protokollrevision 2026-07-28 trägt jede Anfrage die Client-Fähigkeiten von Claude Code unter params._meta["io.modelcontextprotocol/clientCapabilities"], mit "io.modelcontextprotocol/tasks": {} unter extensions. Eine tools/call-Anfrage, die nicht zu einem Task werden kann, lässt diese Erweiterung weg.

Den Aufruf mit einem Task beantworten

Antworten Sie nur dann mit einem Task, wenn die Anfrage die Erweiterung enthält, sonst erhält Claude den Tool-Fehler Unsupported result type 'task' for tools/call. Claude erhält denselben Fehler, wenn taskId, status, createdAt, lastUpdatedAt oder ttlMs fehlt. Das Task-Objekt ist das JSON-RPC-result Ihrer tools/call-Antwort, benötigt kein content-Array und enthält hier die optionalen Felder statusMessage und pollIntervalMs:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

Bei einem HTTP- oder claude.ai-Konnektor-Server muss die Task-Antwort innerhalb des Timers pro Anfrage beginnen. Nehmen Sie daher den Auftrag an und antworten Sie zuerst, und erledigen Sie dann die Arbeit.

Status, Ergebnisse und Fragen melden

Direkt nach der Task-Antwort sendet Claude Code tasks/get mit { "taskId": ... } und wiederholt dies dann einmal pro Abfrageintervall. Die Tasks-Erweiterung verlangt, dass Ihre Antwort "resultType": "complete" zusammen mit taskId, status, createdAt, lastUpdatedAt und ttlMs enthält. ttlMs darf null sein, und statusMessage und pollIntervalMs sind optional. Dieses Beispiel meldet den Build als abgeschlossen:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

Von Plugins bereitgestellte MCP-Server

Plugins können MCP-Server bündeln, die Tools und Integrationen bereitstellen, wenn Sie das Plugin aktivieren.

Wie von Plugins bereitgestellte MCP-Server funktionieren:

• Plugins definieren MCP-Server in .mcp.json im Plugin-Root oder inline in plugin.json
• Wenn Sie ein Plugin aktivieren, startet Claude Code seine MCP-Server automatisch
• Claude Code bietet Plugin-MCP-Werkzeuge neben manuell konfigurierten MCP-Werkzeugen an
• Sie fügen Plugin-Server hinzu und entfernen sie, indem Sie das Plugin installieren oder deinstallieren, nicht mit /mcp-Befehlen. Sie können einen installierten Plugin-Server in /mcp weiterhin ausschalten, was Claude Code daran hindert, sich damit zu verbinden, ohne das Plugin zu entfernen

Beispiel-Plugin-MCP-Konfiguration:

In .mcp.json im Plugin-Root:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Oder inline in plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Von Plugins bereitgestellte MCP-Funktionen:

• Automatischer Lebenszyklus: Server verbinden und trennen sich an diesen Punkten:
  • Beim Sitzungsstart verbindet Claude Code die Server für aktivierte Plugins automatisch. In /mcp kann ein Remote-(HTTP- oder SSE-)Plugin-Server, den Sie zuvor verwendet haben, stattdessen den cached-Status anzeigen; Claude Code verbindet ihn, wenn Claude eines seiner Werkzeuge zum ersten Mal aufruft. Wenn die Verbindung eines Stdio-Plugin-Servers vor weniger als 15 Minuten fehlgeschlagen ist, überspringt Claude Code die Verbindung
  • Wenn Sie ein Plugin während einer Sitzung aktivieren oder deaktivieren, verbindet oder trennt Claude Code seine MCP-Server, wenn die Änderung angewendet wird. Plugin-Änderungen ohne Neustart anwenden beschreibt, wann das ist. In einer Sitzung ohne interaktives Terminal verbindet oder trennt /reload-plugins keine Plugin-MCP-Server; diese Änderungen treten in Ihrer nächsten Sitzung in Kraft
  • Wenn Sie neu laden, behält Claude Code die Live-Verbindungen von Plugin-Servern, deren Konfiguration unverändert ist, und macht dasselbe, wenn Sie die MCP-Serverliste der Sitzung vom Agent SDK ersetzen, ohne sie zu nennen
  • Wenn Sie die Sitzung auf v2.1.246 oder später mit /cd in ein anderes Verzeichnis verschieben, verbindet Claude Code die Server von Plugins, die die Einstellungen des neuen Verzeichnisses aktivieren, und trennt die Server von Plugins, die nicht mehr aktiviert sind, daher müssen Sie /reload-plugins nach der Verschiebung nicht ausführen
  • In Cloud-Sitzungen startet ein MCP-Aufruf an einen Plugin-Server, der noch nicht verbunden ist, etwa direkt nachdem eine inaktive Sitzung aufwacht, den Server bei Bedarf und wartet auf die Verbindung
• Pfad-Platzhalter: ${CLAUDE_PLUGIN_ROOT} wird zum Installationsverzeichnis des Plugins aufgelöst, ${CLAUDE_PLUGIN_DATA} zu seinem Verzeichnis für persistenten Zustand und ${CLAUDE_PROJECT_DIR} zum stabilen Projektstammverzeichnis. Die Substitution gilt für:
  • stdio-Server: command, args, env
  • http-, sse- und ws-Server: url, headers und headersHelper
• Zugriff auf Benutzerumgebung: Zugriff auf dieselben Umgebungsvariablen wie manuell konfigurierte Server
• Mehrere Transporttypen: Unterstützung für Stdio-, SSE-, HTTP- und WebSocket-Transporte, obwohl die Transportunterstützung je nach Server variieren kann

Plugin-Server erscheinen in /mcp mit Indikatoren, die zeigen, dass sie von Plugins stammen.

claude mcp get verbirgt die Werte, die für den Stdio- oder WebSocket-Server eines Plugins konfiguriert sind, da sie Anmeldedaten enthalten können:

• Stdio-Server: Es gibt Command: stdio, eine leere Args:-Zeile und jede Umgebungsvariable als NAME=[REDACTED] aus
• WebSocket-Server: Es gibt URL: ws und jeden Header als <name>: [REDACTED] aus, und claude mcp list zeigt ws anstelle der URL

Um zu sehen, was das Plugin konfiguriert hat, suchen Sie das Plugin auf der Festplatte und lesen Sie seine .mcp.json oder plugin.json.

Namen von Plugin-MCP-Werkzeugen:

Werkzeuge von einem von einem Plugin gebündelten MCP-Server enthalten sowohl den Plugin-Namen als auch den Server-Schlüssel in ihrem aufrufbaren Namen. Die vollständige Form ist mcp__plugin_<plugin-name>_<server-name>__<tool-name>, wobei jedes Zeichen außerhalb von A-Z, a-z, 0-9, _ und - durch _ ersetzt wird. Für den database-tools-Server, der in einem Plugin namens my-plugin gebündelt ist, ist ein query-Werkzeug aufrufbar als:

mcp__plugin_my-plugin_database-tools__query

Verwenden Sie diesen vollständigen Namen, wenn Sie das Werkzeug in Berechtigungsregeln, der allowed-tools-Liste eines Skills, dem tools-Feld eines Subagenten oder einem Hook-Matcher referenzieren. Ein Hook-Matcher, der gegen den bloßen Server-Schlüssel geschrieben ist, wie mcp__database-tools__.*, wird niemals für einen von einem Plugin gebündelten Server ausgelöst.

Der Server selbst registriert sich unter dem bereichsbezogenen Namen plugin:<plugin-name>:<server-name>, wie plugin:my-plugin:database-tools. Verwenden Sie diesen Namen, wo ein konfigurierter Servername erwartet wird, wie im server-Feld eines mcp_tool-Hooks.

Siehe die Plugin-Komponenten-Referenz für Details zum Bündeln von MCP-Servern mit Plugins.

MCP-Installationsbereiche

MCP-Server können auf drei verschiedenen Bereichsebenen konfiguriert werden. Der Bereich, den Sie wählen, steuert, in welchen Projekten der Server geladen wird und ob die Konfiguration mit Ihrem Team geteilt wird. Administratoren können Server auch auf Unternehmensebene über verwaltete Konfiguration bereitstellen oder zur Verfügung stellen.

Lokaler Bereich

Der lokale Bereich ist der Standard. Ein lokal begrenzter Server wird nur in dem Projekt geladen, in dem Sie ihn hinzugefügt haben, und bleibt privat für Sie. Claude Code speichert ihn in ~/.claude.json unter dem Pfad dieses Projekts, daher wird derselbe Server nicht in Ihren anderen Projekten angezeigt. Verwenden Sie den lokalen Bereich für persönliche Entwicklungsserver, experimentelle Konfigurationen oder Server mit Anmeldedaten, die Sie nicht in der Versionskontrolle haben möchten.

[!NOTE]

Der Begriff „lokaler Bereich“ für MCP-Server unterscheidet sich von allgemeinen lokalen Einstellungen. Lokal begrenzte MCP-Server werden in ~/.claude.json (Ihr Home-Verzeichnis) gespeichert, während allgemeine lokale Einstellungen .claude/settings.local.json (im Projektverzeichnis) verwenden. Siehe Einstellungen für Details zu Einstellungsdatei-Speicherorten.

# Einen lokal begrenzten Server hinzufügen (Standard)
claude mcp add --transport http stripe https://mcp.stripe.com

# Lokalen Bereich explizit angeben
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Der Befehl schreibt den Server in den Eintrag für Ihr aktuelles Projekt in ~/.claude.json. Das folgende Beispiel zeigt das Ergebnis, wenn Sie ihn von /path/to/your/project aus ausführen:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Projektbereich

Projektbegrenzte Server ermöglichen Teamzusammenarbeit durch das Speichern von Konfigurationen in einer .mcp.json-Datei im Root-Verzeichnis Ihres Projekts. Wenn Sie einen projektbegrenzten Server hinzufügen, erstellt oder aktualisiert Claude Code automatisch diese Datei mit der entsprechenden Konfigurationsstruktur. Checken Sie .mcp.json in die Versionskontrolle ein, damit alle Mitglieder Ihres Teams die gleichen MCP-Tools und -Dienste erhalten.

# Einen projektbegrenzten Server hinzufügen
claude mcp add --transport http shared-server --scope project https://example.com/mcp

Die resultierende .mcp.json-Datei folgt einem standardisierten Format:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Aus Sicherheitsgründen fordert Claude Code eine Genehmigung an, bevor projektbegrenzte Server aus .mcp.json-Dateien in interaktiven Sitzungen verwendet werden. Um diese Genehmigungswahlmöglichkeiten zurückzusetzen, führen Sie claude mcp reset-project-choices aus.

In claude -p-Läufen, Agent SDK-Sitzungen und Cloud-Sitzungen außerhalb der Threads eines Projekts kann Claude Code diese Abfrage nicht anzeigen: Es lädt projektbegrenzte Server ohne Nachfrage. Claude Code überspringt die Abfrage auch in einer Sitzung, die Sie im bypassPermissions-Modus mit skipDangerousModePermissionPrompt in Ihren Benutzereinstellungen oder in verwalteten Einstellungen starten. Um einen Server trotzdem auszuschließen:

• Fügen Sie ihn zu disabledMcpjsonServers hinzu, was ihn in jedem Berechtigungsmodus blockiert.
• Schließen Sie Projekteinstellungen vollständig mit --setting-sources oder der SDK-Option settingSources aus.
• Starten Sie die Sitzung mit --strict-mcp-config. Claude Code verwendet dann nur die MCP-Server, die Sie mit --mcp-config übergeben. Das Überspringen der Genehmigungsaufforderung für die projektbegrenzten Server, die Claude Code nicht lädt, erfordert Claude Code v2.1.246 oder später; vor v2.1.246 wartete eine strikte Sitzung immer noch auf Genehmigung für diese, was Hintergrundsitzungen beim Start wartend ließ. Siehe Exklusive Kontrolle mit managed-mcp.json für das, was das Flag unter einer verwalteten MCP-Datei tut.

Projektserver-Genehmigungen und Workspace-Vertrauen behandelt, wie Genehmigungen, die im Repository committed sind, mit Workspace-Vertrauen interagieren.

Benutzerbereich

Benutzerbegrenzte Server werden in ~/.claude.json gespeichert und bieten projektübergreifende Zugänglichkeit, wodurch sie über alle Projekte auf Ihrem Computer verfügbar sind und gleichzeitig privat für Ihr Benutzerkonto bleiben. Dieser Bereich funktioniert gut für persönliche Utility-Server, Entwicklungstools oder Dienste, die Sie häufig über verschiedene Projekte hinweg verwenden.

# Einen Benutzer-Server hinzufügen
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Bereichshierarchie und Vorrang

Wenn derselbe Server auf mehreren Bereichen definiert ist, verbindet sich Claude Code einmal damit und verwendet die Definition aus der höchsten Vorrangsquelle. Der gesamte Server-Eintrag aus dieser Quelle wird verwendet; Felder werden nicht über Bereiche hinweg zusammengeführt.

1. Lokaler Bereich
2. Projektbereich
3. Benutzerbereich
4. Von Plugins bereitgestellte Server
5. claude.ai-Connectoren

Claude Code stimmt Duplikate in den drei Bereichen nach Name ab. Plugins und Connectoren stimmen nach Endpunkt ab, daher wird einer, der auf die gleiche URL oder den gleichen Befehl wie ein Server oben verweist, als Duplikat behandelt.

Zwei URL-Schreibweisen zählen als derselbe Endpunkt, wenn sie sich nur im Großbuchstaben des Schemas oder Hosts unterscheiden, dem Standardport des Schemas, wie :443 auf https, oder einem nachgestellten Schrägstrich. Ein anderer Pfad, eine Abfragezeichenfolge, Benutzerinformationen oder ein nicht standardmäßiger Port machen zwei Server unterschiedlich.

Ein Server, den Ihre Organisation über die verwaltete Einstellung managedMcpServers bereitstellt, hat Vorrang vor all diesen, daher verbindet sich Claude Code mit der Definition der Organisation, wenn einer von ihnen ihn dupliziert. Erfordert Claude Code v2.1.259 oder später.

Wenn Sie eine lokale Sitzung in der Code-Registerkarte der Desktop-App mit dem gleichen stdio-Servernamen auf der obersten Ebene von ~/.claude.json (Benutzerbereich) und in .mcp.json öffnen, verwendet die Code-Registerkarte die ~/.claude.json-Definition.

Umgebungsvariablen-Erweiterung in .mcp.json

Claude Code unterstützt die Umgebungsvariablen-Erweiterung in .mcp.json-Dateien, die es Teams ermöglicht, Konfigurationen zu teilen und gleichzeitig Flexibilität für maschinenspezifische Pfade und vertrauliche Werte wie API-Schlüssel zu bewahren.

Unterstützte Syntax

• ${VAR}: erweitert sich zum Wert der Umgebungsvariablen VAR
• ${VAR:-default}: erweitert sich zu VAR, wenn gesetzt, andernfalls wird default verwendet

Erweiterungsorte

Umgebungsvariablen können erweitert werden in:

• command: der Server-Ausführungspfad
• args: Befehlszeilenargumente
• env: Umgebungsvariablen, die an den Server übergeben werden
• url: für HTTP-Server-Typen
• headers: für HTTP-Server-Authentifizierung

Beispiel mit Variablenerweiterung

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

Nicht gesetzte Variablen ohne Standard

Wenn eine referenzierte Umgebungsvariable nicht gesetzt ist und keinen Standardwert hat, wird die Konfiguration trotzdem geladen: Claude Code meldet eine Warnung zu fehlender Variable für diesen Server in der Ausgabe von claude mcp list und verwendet den nicht erweiterten ${VAR}-Text unverändert. Setzen Sie die Variable oder fügen Sie einen :-default-Fallback hinzu, damit der Server mit dem beabsichtigten Wert startet. In einer Remote-Server-url und headers lesen einige Anmeldedatenvariablen als leer statt, ohne Warnung.

Anmeldedatenvariablen, die als leer gelesen werden

In einer Remote-Server-url und headers liest Claude Code Anmeldedatenvariablen aus Ihrer Umgebung als leer statt sie zu erweitern. Dies verhindert, dass ein Projekt .mcp.json oder ein Plugin Ihre Claude Code- oder Cloud-Provider-Anmeldedaten an einen Server sendet, den es benennt. Wenn Sie Bearer ${ANTHROPIC_AUTH_TOKEN} schreiben, erhält der Server Bearer ohne Anmeldedaten und lehnt die Anfrage ab, normalerweise mit einem 401. Claude Code meldet dies als fehlgeschlagene Verbindung.

Die abgedeckten Namen sind:

• Claude Code's eigene Anmeldedaten, wie ANTHROPIC_API_KEY und ANTHROPIC_AUTH_TOKEN
• Ihre Cloud-Provider-Anmeldedaten, wie AWS_BEARER_TOKEN_BEDROCK
• Andere Anmeldedaten, die Ihre Umgebung trägt, wie HTTPS_PROXY und NPM_TOKEN

Ein abgedeckter Name wird als leer gelesen, unabhängig davon, ob Sie die Variable gesetzt haben oder nicht, und ein :-default-Fallback darauf wird ignoriert. Eine Provider-Basis-URL wie ANTHROPIC_BASE_URL wird immer noch erweitert, daher funktioniert "url": "${ANTHROPIC_BASE_URL}/mcp", es sei denn, der Wert der URL selbst bettet eine Anmeldedaten wie einen Benutzernamen und ein Passwort ein.

Ein Name außerhalb dieses Satzes, wie API_KEY, wird wie geschrieben erweitert. Um dem Server eine der abgedeckten Anmeldedaten zu geben, kopieren Sie sie in eine Variable mit einem Namen Ihrer Wahl und referenzieren Sie stattdessen diesen Namen.

Wenn eine Remote-Server-url oder headers eine abgedeckte Variable referenziert, die Sie gesetzt haben, nennt Claude Code sie in einer Debug-Log-Zeile. Um die Zeile zu lesen, führen Sie claude --debug-file /tmp/claude-debug.log aus und durchsuchen Sie diese Datei nach never expanded toward a remote server.

Wie Referenzen in /mcp und CLI-Ausgabe angezeigt werden

Für einen Server im lokalen, Projekt- oder Benutzer-Bereich zeigen die folgenden Oberflächen eine ${VAR}-Referenz nach Name statt als ihren aufgelösten Wert:

• Die URL oder Befehlszeile in der Detailansicht eines Servers unter /mcp
• claude mcp list und claude mcp get Ausgabe

Die /mcp Detailansicht zeigt Referenzen auf diese Weise in Claude Code v2.1.268 oder später.

Für einen Server, den Ihre Organisation über die Einstellung managedMcpServers bereitstellt, zeigen diese Oberflächen nur den Host der URL.

Um zu überprüfen, was claude mcp list, claude mcp get und /mcp anzeigen, wenn eine Verbindung fehlschlägt, siehe Server-Status-Detail.

Praktische Beispiele

Beispiel: Mit GitHub für Code-Reviews verbinden

GitHubs Remote-MCP-Server authentifiziert sich mit einem GitHub-Personal-Access-Token, der als Header übergeben wird. Um einen zu erhalten, öffnen Sie Ihre GitHub-Token-Einstellungen, generieren Sie ein neues feingranulares Token mit Zugriff auf die Repositories, mit denen Claude arbeiten soll, und fügen Sie dann den Server hinzu:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

Ersetzen Sie YOUR_GITHUB_PAT durch Ihr persönliches Zugriffs-Token. Der Befehl claude mcp add speichert die Konfiguration, ohne Anmeldedaten zu validieren, daher wird hier ein Platzhalterwert akzeptiert, aber der Server kann sich später nicht verbinden. Um die Verbindung zu überprüfen, führen Sie /mcp aus und prüfen Sie, ob die Zeile des Servers ein Häkchen anzeigt. Ein Server mit ungültigen Anmeldedaten zeigt stattdessen ein ✘ an, und seine Fehlerdetails enthalten den HTTP-Status, den der Server zurückgegeben hat, z. B. einen 401.

Arbeiten Sie dann mit GitHub:

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

Beispiel: Ihre PostgreSQL-Datenbank abfragen

DBHub, das Paket @bytebase/dbhub, ist ein MCP-Server, der Claude mit einer relationalen Datenbank über die Verbindungszeichenfolge verbindet, die Sie in --dsn übergeben. Verwenden Sie einen schreibgeschützten Datenbankbenutzer in der Verbindungszeichenfolge, damit die Abfragen, die Claude ausführt, keine Daten ändern können:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Um zu bestätigen, dass der Server startet, führen Sie /mcp aus und prüfen Sie, ob die Zeile db ein Häkchen anzeigt.

Fragen Sie dann Ihre Datenbank natürlich ab:

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

Mit Remote-MCP-Servern authentifizieren

Viele Cloud-basierte MCP-Server erfordern Authentifizierung. Claude Code unterstützt OAuth 2.0 für sichere Verbindungen.

Claude Code markiert einen Remote-Server als authentifizierungsbedürftig, wenn der Server mit 401 Unauthorized oder 403 Forbidden antwortet. Was Claude Code anzeigt, hängt vom Server ab:

• Für einen Server, bei dem Sie sich nicht angemeldet haben, kennzeichnet jeder dieser Statuscodes den Server in /mcp, damit Sie den OAuth-Fluss abschließen können.
• Für einen claude.ai-Konnektor kennzeichnet ein 401, das durch die Ablehnung Ihres Sitzungs-Tokens durch claude.ai verursacht wird, den Konnektor nicht, da eine erneute Autorisierung des Konnektors Ihre Anmeldung nicht beheben kann. Claude Code zeigt stattdessen den Zustand „Sitzungs-Token abgelehnt“ an.
• Für einen Server, dessen Authorization-Header Sie konfiguriert haben, in headers oder über einen headersHelper, kennzeichnet ein 401 oder 403 beim Verbinden den Server nicht, da die Anmeldedaten, die behoben werden müssen, diejenigen sind, die Sie konfiguriert haben. Claude Code meldet die Verbindung stattdessen als fehlgeschlagen. Wenn Sie diesen Header aus einer ${VAR}-Referenz gesetzt haben, überprüfen Sie, ob diese Variable eine ist, die Claude Code als leer liest.
• Für einen Konnektor, der an eine Cloud-Sitzung übermittelt wird, führt Claude Code keinen Anmeldungsfluss aus, da der Proxy der Sitzung sich beim Konnektor mit der Autorisierung authentifiziert, die Sie in claude.ai gewährt haben. Wenn ein Konnektor dort erneut autorisiert werden muss, verbinden Sie ihn erneut unter claude.ai/customize/connectors, anstatt aus der Sitzung.

Wenn ein OAuth-Server, bei dem Sie bereits angemeldet sind, Ihr gespeichertes Token mit 401 Unauthorized ablehnt, aktualisiert Claude Code das Token, verbindet sich erneut und wiederholt die Anfrage einmal. Der Server wird in /mcp nur gekennzeichnet, wenn dieser Wiederholungsversuch auch fehlschlägt. In einem claude -p- oder Agent SDK-Lauf unter macOS schlägt eine Anfrage, die Claude Code gesendet hat, während es Ihr gespeichertes Token nicht lesen konnte, stattdessen mit einem Fehler zu gespeicherten Anmeldedaten fehl.

Wenn der Server das gespeicherte Refresh-Token ablehnt, zeigt Claude Code sofort einen Hinweis an, der auf /mcp verweist. Öffnen Sie /mcp und wählen Sie Re-authenticate auf dem Server, um sich erneut anzumelden, bevor der nächste Tool-Aufruf fehlschlägt.

Ein benutzerdefinierter Server, der einen WWW-Authenticate-Header zurückgibt, der auf seinen Autorisierungsserver verweist, erhält die gleiche automatische Erkennung wie jeder andere Remote-Server.

Claude Code zeigt auch einen Starthinweis an, wenn ein oder mehrere konfigurierte Server Authentifizierung benötigen, sodass Sie /mcp nicht öffnen müssen, um zu erkennen, welche Server Anmeldung benötigen. Der Hinweis zählt nur Server, bei denen Sie sich von Claude Code aus anmelden können. Vor v2.1.218 zählte er auch claude.ai-Konnektoren, die nicht in claude.ai verbunden waren und die Sie nur aus den claude.ai-Einstellungen verbinden können.

Der Hinweis kündigt jeden Server einmal an und lässt ihn aus der Zählung bei späteren Starts aus, bis dieser Server verbunden ist und erneut Anmeldung benötigt. /mcp listet immer noch jeden Server auf, der Anmeldung benötigt.

Ein claude -p- oder Agent SDK-Lauf hat kein /mcp-Panel, daher kann Claude Code den OAuth-Fluss dort nicht ausführen. Um einen Server zu verwenden, der Authentifizierung benötigt, schließen Sie die Anmeldung zuerst in einer interaktiven Sitzung ab: Führen Sie /mcp in der Sitzung oder claude mcp login <name> in Ihrer Shell aus. Wenn ein konfigurierter Server während eines claude -p- oder Agent SDK-Laufs mit aktivierter Tool-Suche Authentifizierung benötigt, teilt Claude Code Claude mit, dass die Tools des Servers nicht verfügbar sind, bis Sie ihn autorisieren.

Wenn Sie headers.Authorization für den Server konfiguriert haben und der Server diesen Header ablehnt, meldet Claude Code die Verbindung als fehlgeschlagen, anstatt auf OAuth zurückzugreifen. Überprüfen Sie, dass das Token für den MCP-Endpunkt gültig ist, oder entfernen Sie den Header, um den OAuth-Fluss zu verwenden.

1. Fügen Sie den Server hinzu, der Authentifizierung erfordert

Wenn Sie den sentry-Server bereits in der MCP-Schnellstartanleitung hinzugefügt haben, überspringen Sie diesen Schritt: Das erneute Ausführen von claude mcp add mit dem gleichen Servernamen im gleichen Geltungsbereich schlägt mit MCP server sentry already exists in local config fehl. Führen Sie andernfalls aus:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

2. Verwenden Sie den /mcp-Befehl innerhalb von Claude Code

In Claude Code verwenden Sie den Befehl:

/mcp

Folgen Sie dann den Schritten in Ihrem Browser, um sich anzumelden.

[!TIP]

Tipps:

• Authentifizierungstoken werden sicher gespeichert und automatisch aktualisiert
• Verwenden Sie „Clear authentication“ im /mcp-Menü, um den Zugriff zu widerrufen
• Wenn Ihr Browser nicht automatisch geöffnet wird, kopieren Sie die bereitgestellte URL und öffnen Sie sie manuell
• Wenn die Browser-Umleitung nach der Authentifizierung mit einem Verbindungsfehler fehlschlägt, fügen Sie die vollständige Callback-URL aus der Adressleiste Ihres Browsers in die URL-Eingabeaufforderung ein, die in Claude Code angezeigt wird
• OAuth-Authentifizierung funktioniert mit HTTP-Servern

Authentifizieren Sie sich über die Befehlszeile

Der Befehl claude mcp login <name> führt den OAuth-Fluss eines konfigurierten Servers direkt aus Ihrer Shell aus, sodass Sie das /mcp-Panel nicht innerhalb einer Sitzung öffnen müssen. Für einen claude.ai-Konnektor folgen Sie Einen Konnektor erneut aus Ihrer Shell autorisieren.

claude mcp login sentry

Um gespeicherte Anmeldedaten später zu löschen, führen Sie claude mcp logout <name> aus.

claude mcp login erkennt, wenn kein lokaler Browser verfügbar ist, z. B. während einer SSH-Sitzung oder unter Linux ohne Display-Server, und gibt die Autorisierungs-URL aus, anstatt zu versuchen, einen Browser zu öffnen. Öffnen Sie die URL auf Ihrem lokalen Computer und fügen Sie dann die vollständige Umleitungs-URL aus der Adressleiste Ihres Browsers an der Eingabeaufforderung ein. Der Befehl benötigt ein interaktives Terminal für den Einfügungsschritt, daher verbinden Sie sich mit ssh -t. Übergeben Sie --no-browser, um die URL-Eingabeaufforderung zu erzwingen, auch wenn ein lokaler Browser erkannt wird.

claude mcp login sentry --no-browser

Verwenden Sie einen festen OAuth-Callback-Port

Einige MCP-Server erfordern einen spezifischen Redirect-URI, der im Voraus registriert ist. Standardmäßig wählt Claude Code einen zufällig verfügbaren Port für den OAuth-Callback. Verwenden Sie --callback-port, um den Port zu fixieren, damit er einem vorregistrierten Redirect-URI der Form http://localhost:PORT/callback entspricht. Wenn die Anmeldung auf Claude Code v2.1.229 mit einem Redirect-URI-Mismatch fehlschlägt, siehe den Versionshinweis unter Verwenden Sie vorkonfigurierte OAuth-Anmeldedaten.

Sie können --callback-port allein (mit dynamischer Client-Registrierung) oder zusammen mit --client-id (mit vorkonfigurierten Anmeldedaten) verwenden.

# Fester Callback-Port mit dynamischer Client-Registrierung
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Verwenden Sie vorkonfigurierte OAuth-Anmeldedaten

Einige MCP-Server unterstützen keine automatische OAuth-Einrichtung über Dynamic Client Registration. Wenn Sie einen Fehler wie „Incompatible auth server: does not support dynamic client registration“ sehen, erfordert der Server vorkonfigurierte Anmeldedaten. Claude Code unterstützt auch Server, die ein Client ID Metadata Document (CIMD) anstelle von Dynamic Client Registration verwenden, und erkennt diese automatisch. Wenn die automatische Erkennung fehlschlägt, registrieren Sie zunächst eine OAuth-App über das Entwicklerportal des Servers und geben Sie dann die Anmeldedaten beim Hinzufügen des Servers an.

1. Registrieren Sie eine OAuth-App beim Server

Erstellen Sie eine App über das Entwicklerportal des Servers und notieren Sie sich Ihre Client-ID und Ihr Client-Secret.

Wenn das Registrierungsformular nach einem Redirect-URI fragt, wählen Sie einen verfügbaren Port und geben Sie http://localhost:PORT/callback mit diesem Port ein. Sie werden denselben Port im nächsten Schritt verwenden.

In v2.1.229 sendete Claude Code stattdessen http://127.0.0.1:PORT/callback, und Server, die den registrierten Redirect-URI exakt abgleichen, lehnten die Anmeldung mit einem Redirect-URI-Mismatch ab. Claude Code v2.1.231 stellte die localhost-Form wieder her. Um das Problem auf v2.1.229 zu beheben, aktualisieren Sie Claude Code, oder fügen Sie vorübergehend die http://127.0.0.1:PORT/callback-Form zu den registrierten Redirect-URIs des Servers hinzu.

2. Fügen Sie den Server mit Ihren Anmeldedaten hinzu

Die Registerkarten behandeln beide Befehle: claude mcp add nimmt Ihre Client-ID und Ihren Callback-Port als Flags, und claude mcp add-json nimmt sie in einem oauth-Objekt. Wenn Sie einen Redirect-URI registriert haben, setzen Sie den Callback-Port auf den Port in diesem URI.

claude mcp add

Verwenden Sie --client-id, um die Client-ID Ihrer App zu übergeben. Das Flag --client-secret fragt das Secret mit maskierter Eingabe ab:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

claude mcp add-json

Fügen Sie das Objekt oauth in die JSON-Konfiguration ein und übergeben Sie --client-secret als separates Flag:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

claude mcp add-json (nur Callback-Port)

Um nur den Callback-Port zu fixieren und Claude Code den Client automatisch registrieren zu lassen, setzen Sie callbackPort allein:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

CI / Umgebungsvariable

Legen Sie das Secret über eine Umgebungsvariable fest, um die interaktive Eingabeaufforderung zu überspringen:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

3. Authentifizieren Sie sich in Claude Code

Führen Sie /mcp in Claude Code aus und folgen Sie dem Browser-Login-Ablauf.

[!TIP]

Tipps:

• Das Client-Secret wird sicher in Ihrem System-Schlüsselbund (macOS) oder einer Datei mit Anmeldedaten gespeichert, nicht in Ihrer Konfiguration
• Sie können das Client-Secret nur beim Hinzufügen des Servers festlegen. Wenn Sie sich mit claude mcp login oder über /mcp authentifizieren, verwendet Claude Code das gespeicherte Secret, fragt nicht danach und liest MCP_CLIENT_SECRET nicht
• Um das Secret später hinzuzufügen oder zu ändern, entfernen Sie den Server mit claude mcp remove <name> und fügen Sie ihn dann erneut mit --client-secret und dem gleichen --scope hinzu
• Wenn der Server einen öffentlichen OAuth-Client ohne Secret verwendet, verwenden Sie nur --client-id ohne --client-secret
• Diese Flags gelten nur für HTTP- und SSE-Transporte. Sie haben keine Auswirkung auf Stdio-Server
• Verwenden Sie claude mcp get <name>, um zu überprüfen, dass OAuth-Anmeldedaten für einen Server konfiguriert sind

Überschreiben Sie die OAuth-Metadaten-Erkennung

Verweisen Sie Claude Code auf eine spezifische OAuth-Autorisierungsserver-Metadaten-URL, um die Standard-Erkennungskette zu umgehen. Legen Sie authServerMetadataUrl fest, wenn die Standard-Endpunkte des MCP-Servers Fehler zurückgeben, oder wenn Sie die Erkennung durch einen internen Proxy leiten möchten. Standardmäßig überprüft Claude Code zunächst RFC 9728 Protected Resource Metadata unter /.well-known/oauth-protected-resource und fällt dann auf RFC 8414 Authorization Server Metadata unter /.well-known/oauth-authorization-server zurück.

Legen Sie authServerMetadataUrl im Objekt oauth der Konfiguration Ihres Servers in .mcp.json fest:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

Die URL muss https:// verwenden. Die scopes_supported der Metadaten-URL überschreiben die Scopes, die der Upstream-Server bewirbt.

Beschränken Sie OAuth-Scopes

Legen Sie oauth.scopes fest, um die Scopes zu fixieren, die Claude Code während des Autorisierungsflusses anfordert. Dies ist die unterstützte Methode, um einen MCP-Server auf eine von Ihrem Sicherheitsteam genehmigte Teilmenge zu beschränken, wenn der Upstream-Autorisierungsserver mehr Scopes bewirbt, als Sie gewähren möchten. Der Wert ist eine einzelne durch Leerzeichen getrennte Zeichenkette, die dem scope-Parameter-Format in RFC 6749 §3.3 entspricht.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

oauth.scopes hat Vorrang sowohl vor authServerMetadataUrl als auch vor den Scopes, die der Server unter /.well-known entdeckt. Lassen Sie es ungesetzt, damit der MCP-Server die angeforderte Scope-Menge bestimmt.

Wenn oauth.scopes nicht gesetzt ist, fordert Claude Code nicht den vollständigen scopes_supported-Katalog aus automatisch erkannten Authorization Server Metadata an. Metadaten, die von einer konfigurierten authServerMetadataUrl abgerufen werden, liefern weiterhin ihre scopes_supported als die angeforderten Scopes.

Wenn der Autorisierungsserver offline_access in scopes_supported bewirbt, fügt Claude Code es zu den fixierten Scopes hinzu, damit das Zugriffs-Token ohne neue Browser-Anmeldung aktualisiert werden kann.

Wenn der Server später einen 403 insufficient_scope für einen Tool-Aufruf zurückgibt, schlägt der Aufruf mit einer needs additional permissions-Nachricht fehl, die den Scope benennt, den der Server anfordert. Der Server wird als authentifizierungsbedürftig in /mcp angezeigt.

Wenn dieser Scope nicht in Ihrem fixierten oauth.scopes enthalten ist, fügen Sie ihn hinzu, führen Sie dann /mcp aus und authentifizieren Sie den Server erneut. Claude Code fordert die fixierten Scopes an, nicht den Scope, den der Server benannt hat. Wenn Sie sich also erneut authentifizieren, ohne ihn hinzuzufügen, fehlt er dem Token, das Sie erhalten, weiterhin.

Verwenden Sie dynamische Header für benutzerdefinierte Authentifizierung

Wenn Ihr MCP-Server ein anderes Authentifizierungsschema als OAuth verwendet, wie Kerberos, kurzlebige Token oder ein internes SSO, verwenden Sie headersHelper, um Anfrage-Header zur Verbindungszeit zu generieren. Claude Code führt den Befehl aus und führt seine Ausgabe mit den Verbindungs-Headern zusammen.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

Der Befehl kann auch inline sein:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Anforderungen:

• Der Befehl muss ein JSON-Objekt mit String-Schlüssel-Wert-Paaren auf stdout schreiben
• Claude Code führt den Befehl in einer Shell aus und bricht ihn nach 10 Sekunden ab
• Claude Code wählt das Arbeitsverzeichnis des Befehls danach, wo Sie den Server konfiguriert haben, geben Sie das Skript daher als absoluten Pfad an oder legen Sie es in den PATH
• Dynamische Header überschreiben alle statischen headers mit dem gleichen Namen

Claude Code führt den Helper bei jeder Verbindung neu aus, beim Sitzungsstart und bei Wiederverbindung, sobald die Vertrauensregel für Server im Projekt- und lokalen Geltungsbereich ihn ausführen lässt. Das Ergebnis wird nicht zwischengespeichert, daher ist Ihr Skript für jede Token-Wiederverwendung verantwortlich.

Wenn ein Tool-Aufruf 401 Unauthorized oder 403 Forbidden zurückgibt, führt Claude Code den Helper automatisch unter der gleichen Regel erneut aus, verbindet sich mit den neuen Headern erneut und wiederholt den Aufruf einmal. Claude Code markiert den Server als authentifizierungsbedürftig in /mcp nur, wenn dieser Wiederholungsversuch auch fehlschlägt.

Wenn die Ausgabe des Helpers einen Authorization-Header enthält, verwendet Claude Code diese Anmeldedaten als Authentifizierung des Servers und fällt für den Server nicht auf OAuth zurück.

Wenn der Server die Anmeldedaten des Helpers beim Verbinden ablehnt, meldet Claude Code die Verbindung als fehlgeschlagen, anstatt den Server als authentifizierungsbedürftig zu markieren. Beheben Sie die Anmeldedaten, die Ihr Helper zurückgibt, und verbinden Sie sich dann über /mcp erneut, um den Helper erneut auszuführen.

Claude Code setzt diese Umgebungsvariablen beim Ausführen des Helpers:

Verwenden Sie diese, um ein einzelnes Helper-Skript zu schreiben, das mehrere MCP-Server bedient.

Ein von einem Plugin bereitgestellter headersHelper kann nicht auf die ${user_config.*}-Werte des Plugins verweisen, da der Befehl durch eine Shell ausgeführt wird. Claude Code meldet den Server mit einem Fehler als fehlkonfiguriert und ersetzt den Wert nicht. Setzen Sie ${user_config.KEY} stattdessen in das Feld headers des Servers, das nicht von der Shell geparst wird, oder lassen Sie das Helper-Skript den Wert aus einer Konfigurationsdatei lesen. Vor v2.1.207 ersetzte headersHelper ${user_config.*}-Werte.

Wo der Helper ausgeführt wird

Claude Code wählt das Arbeitsverzeichnis des headersHelper-Befehls anhand der Konfiguration, die den Server deklariert. Ein cd, das Claude in Bash ausführt, ändert es nicht, und /cd ändert es nur für Server, die aus dem primären Arbeitsverzeichnis der Sitzung ausgeführt werden. Jede Zeile unten gibt das Verzeichnis an, gegen das ein relativer Pfad in Ihrem headersHelper-Befehl aufgelöst wird.

Vor v2.1.238 führte Claude Code auch die Helper von Servern im Benutzer-Geltungsbereich, von verwalteten Servern und claude.ai-Konnektor-Servern sowie von Agent-Dateien von außerhalb Ihres Projekts aus dem Verzeichnis aus, in dem Sie es gestartet haben.

Welche Variablen ein Helper lesen kann

Ein headersHelper, den ein Repository oder Plugin bereitstellt, ist ein Befehl, den Sie nicht geschrieben haben, daher führt Claude Code ihn ohne die Anmeldedaten-Variablen aus Ihrer Umgebung aus, wie z. B. ANTHROPIC_API_KEY. Wo Sie den Server konfiguriert haben, entscheidet, ob dies zutrifft:

• Entfernt: ein Server in einer Projekt-.mcp.json oder in einem Plugin sowie ein Inline-Server in einer Agent-Datei aus Ihrem Projekt oder aus einem --add-dir-Verzeichnis
• Nicht entfernt: ein Server im Benutzer- oder lokalen Geltungsbereich, in verwaltetem MCP, von einem claude.ai-Konnektor oder bereitgestellt vom SDK oder über --mcp-config sowie ein Inline-Server in einer Agent-Datei aus ~/.claude/agents/, aus verwalteten Einstellungen oder übergeben mit --agents

Abgesehen von Gits GIT_CONFIG_KEY_<n>-Variablen entfernt Claude Code jede Variable aus Ihrer Umgebung, deren Name nach Anmeldedaten aussieht, wie z. B. ein Name, der TOKEN, SECRET, PASSWORD, KEY oder AUTH in beliebiger Groß- oder Kleinschreibung enthält, daher werden sowohl ANTHROPIC_API_KEY als auch MY_REGISTRY_TOKEN entfernt. Claude Code entfernt auch eine feste Liste von Anmeldedaten-Variablen, deren Namen diesem Muster nicht folgen, wie z. B. ANTHROPIC_CUSTOM_HEADERS.

Wenn dies auf Ihren Helper zutrifft, lassen Sie das Skript seine Anmeldedaten aus einer Datei oder einem Anmeldedaten-Speicher lesen. Wenn die url des Servers den aktuellen Wert einer dieser Variablen enthält, wie z. B. MY_REGISTRY_TOKEN, ist dieser Teil im CLAUDE_CODE_MCP_SERVER_URL-Wert, den der Helper erhält, ebenfalls durch REDACTED ersetzt.

Vertrauen Sie einem Ordner, bevor sein headersHelper ausgeführt wird

Claude Code führt einen headersHelper als beliebigen Shell-Befehl aus. Für einen Server in einer Projekt-.mcp.json oder im lokalen Geltungsbereich führt es den Helper nur aus, nachdem Sie den Vertrauensdialog für das Projektverzeichnis akzeptiert haben, in dem der Server deklariert ist. Vor v2.1.238 führte eine claude -p- oder SDK-Sitzung diese Helper ohne Vertrauensprüfung aus, und eine interaktive Sitzung führte sie aus, sobald Sie einem übergeordneten Ordner vertraut hatten.

• Vertrauen, das nicht zählt: das Vertrauen eines übergeordneten Ordners und das automatische Vertrauen, das eine claude -p- oder SDK-Sitzung für Hooks in Einstellungsdateien erhält
• Bis Sie dem Ordner vertrauen: Claude Code verbindet den Server nur mit seinen statischen headers. In einer claude -p- oder SDK-Sitzung gibt es außerdem pro Server eine headersHelper not run-Zeile auf stderr aus, die Ihnen mitteilt, wie Sie das Vertrauen gewähren.
• Vertrauen ohne Dialog: Setzen Sie projects["<path>"].hasTrustDialogAccepted in ~/.claude.json auf true. <path> ist der Ordner, an den Claude Code das Vertrauen laut Project allow rules and workspace trust bindet.

Claude Code wendet die gleiche Regel auf einen Server an, der inline in einer Agent-Datei deklariert ist, und überprüft, woher diese Agent-Datei stammt: aus Ihrem Projekt, für eine Datei in dessen .claude/agents/-Verzeichnis, oder aus einem --add-dir-Verzeichnis. Bis Sie diesem Projekt oder Verzeichnis selbst vertrauen, lädt Claude Code den Server überhaupt nicht, daher wird sein Helper auch nie ausgeführt.

Melden Sie sich bei einem MCP-Server hinter einem Gateway an, das einen Header erfordert

Die OAuth-Anmeldung bei einem MCP-Server schlägt fehl, wenn ein Gateway einen Header wie X-API-Key erfordert und Claude Code ihn nicht sendet. Damit Claude Code diesen Header sendet, fügen Sie ihn der Konfiguration des Servers hinzu und verwenden Sie Claude Code v2.1.299 oder höher:

• Ein Server, dessen Konfiguration Sie bearbeiten können: Setzen Sie ihn in headers oder geben Sie ihn aus einem headersHelper zurück
• Ein Server, den verwaltetes MCP oder ein Plugin bereitstellt: Bitten Sie Ihren Administrator oder den Autor des Plugins, den Header zum Eintrag des Servers hinzuzufügen

Claude Code fügt die konfigurierten Header außer Authorization dann den Anfragen für Anmeldung, Token-Aktualisierung und Token-Widerruf hinzu, die es an den Origin des Servers sendet. Der Origin des Servers besteht aus Schema, Host und Port in seiner url. Ein Gateway, das den Header erfordert, kann die Anmeldung dennoch auf der Autorisierungsseite oder bei einem Autorisierungsserver auf einem anderen Origin stoppen:

• Die Autorisierungsseite: Sie melden sich auf dieser Seite in Ihrem Browser an, der die konfigurierten Header nicht sendet. Wenn Ihr Browser statt der Seite den Fehler des Gateways erhält, bitten Sie die für das Gateway verantwortliche Person, die Seite ohne den Header durchzulassen.
• Ein Autorisierungsserver auf einem anderen Origin: Wenn ein Gateway vor diesem Server den Header ebenfalls erfordert, schlägt die Anmeldung dort fehl. Bitten Sie die für dieses Gateway verantwortliche Person, OAuth-Anfragen ohne den Header durchzulassen.

MCP-Server aus JSON-Konfiguration hinzufügen

Wenn Sie eine JSON-Konfiguration für einen MCP-Server haben, können Sie sie direkt hinzufügen:

1. Fügen Sie einen MCP-Server aus JSON hinzu

# Grundlegende Syntax
claude mcp add-json <name> '<json>'

# Beispiel: Hinzufügen eines HTTP-Servers mit JSON-Konfiguration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Beispiel: Hinzufügen eines Stdio-Servers mit JSON-Konfiguration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Beispiel: Hinzufügen eines HTTP-Servers mit vorkonfigurierten OAuth-Anmeldedaten
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

2. Überprüfen Sie, dass der Server hinzugefügt wurde

claude mcp get weather-api

[!TIP]

Tipps:

• Stellen Sie sicher, dass das JSON in Ihrer Shell ordnungsgemäß escaped ist
• Das JSON muss dem MCP-Server-Konfigurationsschema entsprechen
• Sie können --scope user verwenden, um den Server zu Ihrer Benutzerkonfiguration statt zur projektspezifischen hinzuzufügen

MCP-Server aus Claude Desktop importieren

Wenn Sie bereits MCP-Server in Claude Desktop konfiguriert haben, können Sie diese importieren:

1. Importieren Sie Server aus Claude Desktop

# Grundlegende Syntax 
claude mcp add-from-claude-desktop 

2. Wählen Sie aus, welche Server importiert werden sollen

Nach dem Ausführen des Befehls wird ein interaktives Dialogfeld angezeigt, in dem Sie auswählen können, welche Server Sie importieren möchten.

3. Überprüfen Sie, dass die Server importiert wurden

claude mcp list 

Servernamen, die über claude mcp-Befehle hinzugefügt werden, dürfen nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthalten. Claude Desktop wendet diese Einschränkung nicht an, daher kann ein Claude Desktop-Server, dessen Name ein anderes Zeichen wie ein Leerzeichen enthält, nicht importiert werden. Der Import meldet jeden Namen, den er ablehnt, und importiert weiterhin die anderen Server, die Sie ausgewählt haben.

[!TIP]

Tipps:

• Diese Funktion funktioniert nur auf macOS und Windows Subsystem for Linux (WSL)
• Sie liest die Claude Desktop-Konfigurationsdatei von ihrem Standardort auf diesen Plattformen
• Verwenden Sie das Flag --scope user, um Server zu Ihrer Benutzerkonfiguration hinzuzufügen
• Importierte Server behalten die gleichen Namen wie in Claude Desktop, wenn der Name nur Buchstaben, Zahlen, Bindestriche und Unterstriche enthält. Claude Code meldet einen Server, dessen Name ein anderes Zeichen enthält, und überspringt ihn
• Wenn Server mit den gleichen Namen bereits vorhanden sind, erhalten sie ein numerisches Suffix (zum Beispiel server_1)

MCP-Server von claude.ai verwenden

Wenn Sie sich bei Claude Code mit einem claude.ai-Konto angemeldet haben, sind MCP-Server, die Sie in claude.ai hinzugefügt haben, bekannt als Konnektoren, automatisch in Claude Code verfügbar:

1. MCP-Server in claude.ai konfigurieren

Fügen Sie Server unter claude.ai/customize/connectors hinzu. Bei Team- und Enterprise-Plänen können nur Admins Server hinzufügen.

2. MCP-Server authentifizieren

Führen Sie alle erforderlichen Authentifizierungsschritte in claude.ai durch.

3. Server in Claude Code anzeigen und verwalten

Verwenden Sie in Claude Code den Befehl:

/mcp

Server von claude.ai werden in der Liste mit Indikatoren angezeigt, die zeigen, dass sie von claude.ai stammen.

Anthropic stellt auch einige Konnektoren selbst bereit, ohne dass Sie oder ein Admin sie hinzufügen. Bei Konten, auf denen Claude Docs verfügbar ist, listet /mcp claude.ai Claude Docs ohne Setup auf, und Claude verwendet es, wenn Sie um ein Dokument für andere Personen bitten. Um nur diesen Konnektor auszuschalten, lesen Sie claude.ai-Konnektoren deaktivieren.

Claude Code markiert einen Konnektor als managed in /mcp und im /plugin-Manager, wenn Ihre Organisation dessen Authentifizierung in claude.ai verwaltet. Der Status „Managed“ ändert nicht, wie Claude Code sich mit dem Konnektor verbindet oder wie die Tool-Kontrollen Ihrer Organisation angewendet werden.

Konnektoren, bei denen Sie sich noch nie angemeldet haben, werden hinter einer Zeile Show unused connectors am Ende des claude.ai-Abschnitts ausgeblendet, damit eine von der Organisation bereitgestellte Liste das Panel nicht ausfüllt. Wählen Sie die Zeile aus, um sie zu erweitern. Ein Konnektor, bei dem Sie sich zuvor angemeldet haben, bleibt sichtbar, auch wenn er derzeit eine erneute Authentifizierung benötigt.

Konnektoren von claude.ai werden nur abgerufen, wenn Ihre aktive Authentifizierungsmethode ein claude.ai-Abonnement-Login ist. Sie werden nicht geladen, auch wenn Sie zuvor /login ausgeführt haben, wenn:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN oder apiKeyHelper aktiv ist
• Ein Drittanbieter wie Amazon Bedrock oder Google Cloud's Agent Platform aktiv ist
• ANTHROPIC_PROFILE, die Federation-Variablen oder ein aktives Anthropic-Profil die Anmeldedaten bereitstellt
• CLAUDE_CODE_OAUTH_TOKEN ein Token von claude setup-token enthält, das nur Modellanfragen stellen kann

Wenn /mcp einen Konnektor, den Sie hinzugefügt haben, nicht auflistet, führen Sie /status aus, um zu bestätigen, welche Authentifizierungsmethode aktiv ist. Heben Sie diese Umgebungsvariable auf, entfernen Sie die apiKeyHelper-Einstellung oder schalten Sie das Profil aus, und führen Sie dann /login aus, um Ihr claude.ai-Konto auszuwählen.

Wenn ein temporäres Netzwerkproblem verhindert, dass die Konnektor-Liste beim Start Ihrer Sitzung geladen wird, versucht Claude Code den Abruf bis zu dreimal im Hintergrund erneut, und die Konnektoren werden angezeigt, sobald ein Wiederholungsversuch erfolgreich ist. Wenn sie immer noch nicht angezeigt werden, starten Sie Claude Code neu, um die Liste erneut abzurufen.

Wenn /mcp einen Konnektor als session token rejected anzeigt oder seine Detailansicht claude.ai rejected the session token anzeigt, hat claude.ai das Token aus Ihrem Claude Code-Login abgelehnt. Die erneute Autorisierung des Konnektors löscht diesen Status nicht, da die eigene Autorisierung des Konnektors in claude.ai nicht das ist, was abgelehnt wurde. Um dies zu beheben:

1. Führen Sie /login aus, um sich erneut anzumelden.
2. Verbinden Sie den Konnektor erneut von /mcp.

Vor v2.1.222 markierte Claude Code Konnektoren stattdessen als authentifizierungsbedürftig, und deren Autorisierung löste das Problem nicht.

Ein Server, den Sie in Claude Code hinzugefügt haben, hat Vorrang vor einem claude.ai-Konnektor, der auf dieselbe URL verweist. In diesem Fall listet /mcp den Konnektor als verborgen auf und zeigt, wie Sie das Duplikat entfernen können, wenn Sie lieber den Konnektor verwenden möchten.

Einige von Anthropic gehostete Konnektoren wie Microsoft 365, Gmail und Google Calendar unterstützen kein lokales OAuth von Claude Code, da der vorgelagerte Identitätsanbieter nur die Umleitungs-URL akzeptiert, die claude.ai registriert hat. Wenn ein Server, den Sie mit claude mcp add oder in .mcp.json hinzugefügt haben, auf einen dieser Hosts verweist und Sie sich von /mcp oder mit claude mcp login darin anmelden, zeigt Claude Code is Anthropic-hosted and doesn't support local OAuth an und leitet Sie stattdessen dazu, den Dienst unter claude.ai/customize/connectors zu verbinden.

Nachdem Sie Ihren Eintrag mit claude mcp remove <name> entfernt und den Dienst auf claude.ai verbunden haben, wird der Konnektor automatisch in Claude Code angezeigt.

Wie Konnektoren Claude Code erreichen

Welche Einstellungen einen claude.ai-Konnektor steuern, hängt davon ab, wo Ihre Sitzung ausgeführt wird, da nur einige Sitzungen Konnektoren selbst von claude.ai abrufen. Jede Zeile unten benennt, wie Konnektoren in einer Art von Sitzung ankommen und was sie dort steuert. Die WSL-Sitzungen der Desktop-App haben keine Zeile, da Konnektoren für sie noch schrittweise eingeführt werden.

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS und allowAllClaudeAiMcps wirken sich nur auf die erste Zeile aus, die Konnektoren, die Claude Code selbst abruft. Die anderen beiden Zeilen unterscheiden sich davon auf diese Weise:

• Cloud-Sitzungen: allowedMcpServers- und deniedMcpServers-Einträge, die die Sitzung erreichen, beispielsweise durch Server-verwaltete Einstellungen, filtern auch die bereitgestellten Konnektoren. Der Proxy der Sitzung schreibt die URL jedes Konnektors um, daher passt ein serverUrl-Muster, das für die eigene URL des Konnektors geschrieben wurde, nicht dazu. Um bereitgestellte Konnektoren neben einer URL-Allowlist in einer selbstgehosteten Umgebung zuzulassen, fügen Sie die serverUrl-Einträge hinzu, die unter Konnektor-Datenverkehr verlässt Ihr Netzwerk aufgelistet sind. Claude Code verwirft die bereitgestellten Konnektoren, wenn eine managed-mcp.json auf dem Host vorhanden ist, der die Sitzung ausführt, z. B. ein selbstgehosteter Runner-Host, unabhängig davon, ob Sie allowAllClaudeAiMcps setzen.
• Lokale und SSH-Sitzungen der Desktop-App: Die Desktop-App registriert die Konnektoren als prozessinterne type: "sdk"-Server, und keine MCP-Einstellung oder managed-mcp.json erreicht sie. Ein Benutzer hält einen Konnektor aus seinen eigenen Sitzungen heraus, indem er ihn unter claude.ai/customize/connectors trennt. Eine Organisation blockiert die Tools eines Konnektors oder schaltet Claude Code in der Desktop-App ganz aus.

Organisationskontrollen für Konnektor-Tools

Ihre Organisation kann Pro-Tool-Kontrollen auf claude.ai-Konnektoren setzen. Claude Code liest diese Einstellungen beim Start und erzwingt sie lokal, außer in den lokalen und SSH-Sitzungen der Desktop-App. Dort hält die Desktop-App blocked-Tools zurück, bevor sie einen Konnektor liefert, und die ask-Einstellung erreicht Claude Code nicht, daher wendet es die gewöhnlichen Berechtigungsregeln der Sitzung auf diese Tools an, anstatt bei jedem Aufruf nachzufragen. In Sitzungen, in denen Claude Code Konnektoren selbst abruft, führen Sie /mcp aus, um zu sehen, welche Einstellung für jedes Tool auf einem Konnektor gilt.

• Tool auf ask gesetzt: Claude Code fragt bei jedem Aufruf mit dem Grund Your organization requires approval for this tool nach. Die Berechtigungsabfrage wird auch in den Berechtigungsmodi acceptEdits, auto und bypassPermissions angezeigt. Im Terminal bietet die Berechtigungsabfrage keine Option, Ihre Wahl zu merken. allow-Regeln, die auf das Tool zutreffen, überspringen die Berechtigungsabfrage auch nicht. Im dontAsk-Modus, der niemals nachfragt, lehnt Claude Code den Aufruf stattdessen ab.
• Tool auf blocked gesetzt: Claude Code filtert das Tool heraus, bevor Claude es sieht, daher wird es nie in Claudes Tool-Liste angezeigt. In Sitzungen, in denen Claude Code Konnektoren selbst abruft, zeigt die /mcp-Tool-Liste das Tool immer noch an, markiert als disabled by your organization.

Die Desktop-App und der claude.ai-Chat wenden die gleiche blocked-Einstellung an, daher kann Claude ein blockiertes Tool dort auch nicht verwenden, und Sie können ein Tool nicht von den Sitzungen der Desktop-App fernhalten, während Sie es im Chat verfügbar halten. Die Desktop-App überspringt einen Konnektor, dessen Tools alle blockiert sind.

claude.ai-Konnektoren deaktivieren

Claude Code wendet disableClaudeAiConnectors nur auf die Konnektoren an, die es selbst abruft, nicht auf die Konnektoren, die ein Cloud-Host oder die Desktop-App liefert. Um die Konnektoren auszuschalten, die es abruft, setzen Sie die Einstellung in einem beliebigen Geltungsbereich auf true:

{
  "disableClaudeAiConnectors": true
}

Diese Einstellung verwendet Any-Source-True-Semantik: true in einer beliebigen Einstellungsquelle hat Vorrang. Eine eingecheckte Projekt-.claude/settings.json kann ein Repository von den Konnektoren abmelden, die Claude Code selbst abruft, aber ein false auf Projektebene kann Konnektoren nicht erneut aktivieren, die ein true auf Benutzer- oder Richtlinienebene deaktiviert hat. Server, die explizit über --mcp-config übergeben werden, sind nicht betroffen.

Sie können auch die Umgebungsvariable ENABLE_CLAUDEAI_MCP_SERVERS auf false setzen, was den gleichen Effekt für die aktuelle Shell-Sitzung hat:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Um einzelne claude.ai-Konnektoren zu blockieren, anstatt alle zu blockieren, fügen Sie sie nach Name oder nach URL-Muster zu deniedMcpServers hinzu. Beispielsweise blockiert ein serverName-Eintrag von "claude.ai Slack" den Slack-Konnektor. Sie können auch /mcp ausführen, um einen beliebigen Konnektor, den Claude Code abruft, nur für das aktuelle Projekt ein- oder auszuschalten.

Claude Code als MCP-Server verwenden

Sie können Claude Code selbst als MCP-Server verwenden, mit dem sich andere Anwendungen verbinden können:

# Claude als stdio MCP-Server starten
claude mcp serve

Der Befehl gibt bei der Ausführung nichts aus. Ein stdio MCP-Server kommuniziert über stdin und stdout, daher bedeutet ein stilles, blockiertes Terminal, dass der Server läuft und auf einen Client wartet, der sich verbindet.

Sie können dies in Claude Desktop verwenden, indem Sie diese Konfiguration zu claude_desktop_config.json hinzufügen:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

[!WARNING]

Konfigurieren des ausführbaren Pfads: Das Feld command muss auf die Claude Code-Ausführungsdatei verweisen. Wenn der Befehl claude nicht in Ihrem System-PATH vorhanden ist, müssen Sie den vollständigen Pfad zur Ausführungsdatei angeben.

So finden Sie den vollständigen Pfad:

which claude

Verwenden Sie dann den vollständigen Pfad in Ihrer Konfiguration:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Ohne den korrekten Pfad zur Ausführungsdatei treten Fehler wie spawn claude ENOENT auf.

[!TIP]

Tipps:

• Versuchen Sie in Claude Desktop, Claude zu bitten, Dateien in einem Verzeichnis zu lesen, Änderungen vorzunehmen und mehr.
• Dieser MCP-Server stellt nur die Tools von Claude Code Ihrem MCP-Client zur Verfügung, daher ist Ihr eigener Client dafür verantwortlich, Benutzerbestätigungen für einzelne Tool-Aufrufe zu implementieren.

Die Ausgabe eines Hintergrundbefehls als MCP-Client lesen

Ein Feld backgroundOutputPath in einem Bash- oder PowerShell-Ergebnis von claude mcp serve bedeutet, dass der Aufruf seinen Befehl im Hintergrund weiterlaufen ließ. Ein Befehl läuft im Hintergrund, wenn Ihr Client beim Aufruf run_in_background: true setzt. Ein Befehl im Vordergrund kann auch in den Hintergrund wechseln, wenn er seinen Timeout erreicht.

Das Feld befindet sich im JSON-Text des Ergebnisses und enthält den Pfad der Ausgabedatei des Befehls.

• Um die bisherige Ausgabe zu lesen: Öffnen Sie die Datei unter diesem Pfad von Ihrem Client aus, oder übergeben Sie den Pfad als file_path an das Read-Tool des Servers
• Um zu erkennen, wann der Befehl abgeschlossen ist: Hängen Sie ein echo einer festen Zeichenfolge an den Wert von command an, etwa npm test; echo DONE. Der Befehl ist abgeschlossen, sobald diese Zeichenfolge in der Datei erscheint. Ohne die Zeichenfolge markiert nichts das Ende, da Claude Code der Datei keine abschließende Zeile hinzufügt und Ihren Client nicht benachrichtigt.
• Um das Ende einer langen Ausgabe zu lesen: Read nur mit file_path gibt die erste Seite zurück oder schlägt fehl, wenn die Datei die Größenbeschränkung überschreitet. Übergeben Sie zusätzlich offset und limit, was bei jeder Dateigröße funktioniert:
  1. Rufen Sie Read mit offset und limit jeweils auf 1 gesetzt auf, und entnehmen Sie totalLines dem Ergebnis
  2. Rufen Sie Read erneut auf, mit offset auf totalLines minus neun und limit auf 10 gesetzt
  3. Suchen Sie Ihre echo-Zeichenfolge in den letzten zehn Zeilen, die der zweite Aufruf zurückgibt

Das Feld backgroundOutputPath erfordert Claude Code v2.1.295 oder höher.

MCP-Ausgabebegrenzungen und Warnungen

Wenn MCP-Tools große Ausgaben erzeugen, hilft Claude Code dabei, die Token-Nutzung zu verwalten, um Ihren Gesprächskontext nicht zu überlasten:

• Warnungsschwelle für Ausgaben: Claude Code zeigt eine Warnung an, wenn eine MCP-Tool-Ausgabe 10.000 Token überschreitet
• Konfigurierbare Begrenzung: Sie können die maximale zulässige MCP-Ausgabe-Token-Menge mithilfe der Umgebungsvariablen MAX_MCP_OUTPUT_TOKENS anpassen
• Standardbegrenzung: Das Standardmaximum beträgt 25.000 Token
• Geltungsbereich: Die Umgebungsvariable gilt für Tools, die keine eigene Begrenzung deklarieren. Tools, die anthropic/maxResultSizeChars setzen, verwenden diesen Wert stattdessen für Textinhalte, unabhängig davon, auf welchen Wert MAX_MCP_OUTPUT_TOKENS gesetzt ist. Tools, die Bilddaten zurückgeben, unterliegen weiterhin MAX_MCP_OUTPUT_TOKENS
• Über der Begrenzung: Wenn ein erfolgreiches Ergebnis ohne Bildinhalt die Token-Begrenzung überschreitet, speichert Claude Code es in einer Datei und ersetzt es in der Konversation durch eine Nachricht, die den Dateipfad benennt, damit Claude die Datei liest, wenn sie den Inhalt benötigt. Die Datei befindet sich im Verzeichnis tool-results der Sitzung unter ~/.claude/projects/.
• Antwortgröße von HTTP- und SSE-Servern: Wenn eine Antwort von einem HTTP- oder SSE-Server 16 MiB überschreitet, beendet Claude Code das Lesen und die Anfrage schlägt fehl. Die Begrenzung gilt nach der Dekomprimierung für einen einzelnen JSON-Response-Body oder ein einzelnes Ereignis eines Event-Streams. Wenn Sie den Server betreuen, geben Sie pro Antwort weniger Daten zurück, um unter der Begrenzung zu bleiben, zum Beispiel durch Paginierung der Ergebnisse
• Nachrichtengröße von WebSocket-Servern: Wenn ein WebSocket-Server eine einzelne Nachricht über 16 MiB sendet, schließt Claude Code die Verbindung, und laufende Aufrufe an diesen Server schlagen fehl. Wenn Sie den Server betreuen, geben Sie pro Nachricht weniger Daten zurück, um unter der Begrenzung zu bleiben

Ein Aufruf, den Claude Code in eine Hintergrundaufgabe verschoben hat, meldet sein Ergebnis über die Aufgabenbenachrichtigung. Für einen Aufruf, der im Vordergrund abgeschlossen wird, gelten zwei weitere Begrenzungen:

• Zeichenbegrenzung für Textergebnisse: Bei einem Tool, das anthropic/maxResultSizeChars nicht deklariert, speichert Claude Code ein erfolgreiches Ergebnis ohne Bildinhalt in einer Datei, sobald es länger als 50.000 Zeichen ist, unabhängig von seiner Token-Anzahl. Das Setzen von MAX_MCP_OUTPUT_TOKENS ändert diesen Schwellenwert nicht
• Fehlerergebnisse: Wenn ein Tool ein Ergebnis zurückgibt, das mit isError: true markiert ist, erhält Claude den Text des Ergebnisses als Fehlermeldung des Tools. Bei Fehlertext, der länger als etwa 11.000 Zeichen ist, bleiben nur die ersten 5.000 und die letzten 5.000 Zeichen erhalten, mit einer Markierung dazwischen, die angibt, wie viele Zeichen entfernt wurden

Um die Token-Begrenzung zu ändern, setzen Sie MAX_MCP_OUTPUT_TOKENS in Ihrer Shell, bevor Sie Claude Code starten:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Erhöhen Sie die Begrenzung für ein bestimmtes Tool

Wenn Sie einen MCP-Server erstellen, können Sie einzelnen Tools ermöglichen, Ergebnisse zurückzugeben, die größer als der standardmäßige Schwellenwert von 50.000 Zeichen für das Speichern auf der Festplatte sind, indem Sie _meta["anthropic/maxResultSizeChars"] im Eintrag der tools/list-Antwort des Tools setzen. Claude Code erhöht den Schwellenwert dieses Tools auf den annotierten Wert, bis zu einer harten Obergrenze von 500.000 Zeichen.

Dies ist nützlich für Tools, die inhärent große, aber notwendige Ausgaben zurückgeben, wie Datenbankschemas oder vollständige Dateistrukturen. Ohne die Anmerkung werden erfolgreiche Ergebnisse, die den Standardschwellenwert überschreiten, auf der Festplatte gespeichert und durch einen Dateiverweis in der Konversation ersetzt.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

Die Anmerkung gilt unabhängig von MAX_MCP_OUTPUT_TOKENS für Textinhalte, sodass Benutzer die Umgebungsvariable nicht für Tools erhöhen müssen, die sie deklarieren. Tools, die Bilddaten zurückgeben, unterliegen weiterhin der Token-Begrenzung.

Bilder in Tool-Ergebnissen

Wenn ein MCP-Tool ein PNG-, JPEG-, GIF- oder WebP-Bild zurückgibt, sieht Claude das Bild inline in der Konversation. Die Inline-Kopie kann verkleinert oder komprimiert werden, um die Bildgrößenlimits des Modells einzuhalten. Claude Code speichert auch die ursprünglichen Bytes in einer Datei im Verzeichnis tool-results der Sitzung unter ~/.claude/projects/ und gibt Claude den Pfad. Claude kann dann die Datei mit vollständiger Auflösung mit Tools wie Bash zuschneiden, konvertieren oder wiederverwenden.

Wenn Sie die Sitzungspersistenz mit --no-session-persistence oder CLAUDE_CODE_SKIP_PROMPT_HISTORY deaktivieren, schreibt Claude Code keine Bilddatei und Claude erhält nur die Inline-Kopie.

Das Speichern von MCP-Bildergebnissen in einer Datei erfordert Claude Code v2.1.283 oder später.

Tool-Eingabeschemas mit einem Kombinator auf Root-Ebene

Einige MCP-Server deklarieren das Eingabeschema eines Tools als JSON-Schema-Union mit anyOf, oneOf oder allOf auf der obersten Ebene des Schemas. Die Claude API akzeptiert diese Schlüsselwörter nicht auf der Schema-Root. Sie akzeptiert Kombinatoren, die in properties verschachtelt sind, die Claude Code unverändert sendet.

Tools mit einem Kombinator auf Root-Ebene bleiben verfügbar. Bevor das Tool an die API gesendet wird, vereinfacht Claude Code das Schema zu einem einzelnen Objekt und stellt dem Beschreibungstext des Tools einen Satz voran, der Claude mitteilt, welche Parametergruppen zusammengehören:

• allOf: Eigenschaften aus jedem Branch werden zusammengeführt, und die required-Liste jedes Branchs gilt weiterhin
• anyOf und oneOf: Eigenschaften aus jedem Branch werden zusammengeführt, und die required-Liste jedes Branchs wird stattdessen in der Tool-Beschreibung beschrieben, anstatt vom Schema erzwungen zu werden

Ihr Server empfängt die Argumente, die Claude ausgewählt hat, daher sollten Sie die Kombination weiterhin serverseitig validieren.

Wenn Claude Code kein Schema erstellen kann, das die API akzeptiert, oder bei einer Bereitstellung, die die Remote-Konfiguration, die das Umschreiben ermöglicht, nicht erhält, überspringt es dieses eine Tool, protokolliert den Grund im Log des Servers und lässt die anderen Tools des Servers verfügbar.

Tools mit ungültigen Eingabeschemas

Die Claude API überprüft das Eingabeschema jedes Tools in einer Anfrage und lehnt die gesamte Anfrage ab, wenn ein Schema fehlschlägt. Ein einzelnes MCP-Tool mit einem fehlerhaften Schema würde daher dazu führen, dass jede Anfrage, die es enthält, mit einem 400-Fehler fehlschlägt. Claude Code führt zwei der API-Überprüfungen selbst durch, wenn es die Tools eines Servers lädt, und schließt jedes Tool aus, das diese Überprüfungen nicht bestehen würde, damit die anderen Tools des Servers weiterhin funktionieren:

• Namen von Eigenschaften auf der obersten Ebene müssen 1 bis 64 Zeichen lang sein und dürfen nur ASCII-Buchstaben und Ziffern, _, . und - verwenden
• Das Schema muss gegen das JSON-Schema-Draft-2020-12-Meta-Schema gültig sein. Claude Code wendet diese Überprüfung auf Schemas an, die kein $schema deklarieren, und auf Schemas, die Draft 2020-12 deklarieren. Ein Schema, das einen anderen Dialekt deklariert, überspringt diese Überprüfung, obwohl die obige Überprüfung der Eigenschaftsnamen weiterhin gilt

Wenn Claude Code ein Tool ausschließt, zeichnet es den Grund im Log des Servers auf und teilt Claude mit, welche Tools es ausgeschlossen hat und warum, damit Sie Claude fragen können, warum ein Tool fehlt. Wenn Sie das Schema auf dem Server korrigieren, wird das Tool beim nächsten Laden der Server-Tools durch Claude Code wieder verfügbar.

Claude Code aktiviert den Ausschluss über ein Feature-Flag, das es von Anthropic abruft. Bei einer Bereitstellung, bei der das Flag-Abrufen deaktiviert ist, oder auf einem Computer, dessen Flags nie angekommen sind, z. B. auf einem isolierten Computer, führt Claude Code die Überprüfungen weiterhin durch und zeichnet im Log des Servers auf, welches Tool abgelehnt würde, sendet das Schema des Tools aber trotzdem an die API. Die API lehnt eine Anfrage, die dieses Schema enthält, mit einem 400-Fehler ab, der das Tool nach seiner Position benennt. Vor v2.1.216 führte keine Bereitstellung diese Überprüfungen durch.

Die Root-Level-Kombinator-Behandlung ist separat und behält ihr eigenes Verhalten bei, wenn das Flag-Abrufen deaktiviert ist oder die Flags nie angekommen sind.

Tools mit Namen, die länger als 128 Zeichen sind

Wenn /mcp ein Tool auflistet, das Claude nicht aufrufen kann, prüfen Sie, ob der vollständige Name des Tools länger als 128 Zeichen ist. Führen Sie /mcp in Ihrer Sitzung aus und wählen Sie das Tool aus, um seinen vollständigen Namen anzuzeigen, zum Beispiel mcp__<server>__<tool>. Claude Code lässt ein MCP-Tool bei den Tools, die es an Claude sendet, weg, wenn sein vollständiger Name länger als 128 Zeichen ist. Die Claude API lehnt eine Anfrage ab, die ein solches Tool enthält. Indem das Tool weggelassen wird, funktionieren die anderen Tools des Servers weiterhin.

Die Meldung, die das Tool benennt, sowie Möglichkeiten, seinen vollständigen Namen zu kürzen, finden Sie unter MCP-Tool-Name länger als 128 Zeichen.

Genehmigung für ein bestimmtes Tool erforderlich

Wenn Sie einen MCP-Server erstellen, können Sie ein Tool so kennzeichnen, dass es bei jedem Aufruf eine explizite Genehmigung erfordert. Setzen Sie dazu _meta["anthropic/requiresUserInteraction"] im Eintrag des Tools in der tools/list-Antwort auf true. Der Wert muss der JSON-Boolean true sein; alle anderen Werte werden ignoriert.

Claude Code zeigt die Berechtigungsabfrage dieses Tools bei jedem Aufruf an, auch in den Berechtigungsmodi acceptEdits, auto und bypassPermissions, und bietet dafür keine Option „Nicht erneut fragen“ an. Allow-Regeln, die auf das Tool zutreffen, überspringen die Abfrage ebenfalls nicht. Im Modus dontAsk, der niemals nachfragt, lehnt Claude Code den Aufruf stattdessen ab.

Die Abfrage muss eine Person erreichen. Im nicht interaktiven Modus mit --permission-prompt-tool wird ein allow-Ergebnis des Prompt-Tools für ein gekennzeichnetes Tool in eine Ablehnung mit der Nachricht MCP tool requires user interaction; not supported via --permission-prompt-tool umgewandelt. Der canUseTool-Callback des Agent SDK empfängt diese Aufrufe dagegen und kann sie genehmigen, da von Ihrer SDK-Anwendung erwartet wird, dass sie diese einem Benutzer anzeigt.

Verwenden Sie dies für Tools, bei denen die Berechtigungsabfrage selbst der Zweck ist, z. B. ein Schritt zur Zustimmung oder zur Zugriffsgewährung, bei dem eine automatische Genehmigung bedeuten würde, dass nie ein Mensch zugestimmt hat. Andere Tools desselben Servers behalten ihr normales Berechtigungsverhalten.

Der folgende tools/list-Eintrag kennzeichnet ein Tool als immer genehmigungspflichtig.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Einige Oberflächen, wie Remote Control und Anwendungen, die auf dem Agent SDK basieren, ermöglichen es Ihnen normalerweise, Tool-Aufrufe mit einem Tippen zu genehmigen. Für ein Tool, das mit dieser Annotation gekennzeichnet ist, hält Claude Code die Aktion mit einem Tippen zurück und zeigt stattdessen die vollständige Berechtigungsabfrage des Tools an. So stammt die Genehmigung weiterhin von einer Person, die die Abfrage beantwortet, und nicht von einem bloßen Tippen.

Claude Code hält die Genehmigung mit einem Tippen auf die gleiche Weise für jede Berechtigungsanfrage zurück, die nur der Terminal-Dialog vollständig darstellen kann, z. B. eine Anfrage mit einer Sicherheitswarnung oder einer Option „Immer zulassen“, die die Remote-Oberfläche nicht anzeigen kann. Sie beantworten diese Anfrage im Terminal-Dialog statt über Remote Control.

Tools markieren, die sicher zweimal aufgerufen werden können

Wenn Sie einen MCP-Server entwickeln, markieren Sie die Tools, die sicher zweimal aufgerufen werden können, damit Claude Code einen Aufruf wiederholen kann, der beim Schließen einer Verbindung noch ausstand. Claude Code kann einen solchen Aufruf an einen HTTP-Server oder einen claude.ai-Konnektor einmal über eine neue Verbindung wiederholen. Ein Aufruf, den Claude Code nicht wiederholt, kann mit connection closed before the tool call was answered fehlschlagen.

Um ein Tool zu markieren, setzen Sie eine dieser annotations in seinem tools/list-Eintrag auf true:

• idempotentHint: Das Tool kann etwas ändern, und ein erneuter Aufruf mit denselben Argumenten ist sicher
• readOnlyHint: Das Tool ändert nichts. Claude Code führt die Aufrufe des Tools außerdem parallel zu anderen nur lesenden Aufrufen aus.

Beispielsweise markieren diese Felder in einem tools/list-Eintrag das Tool set_issue_status als sicher wiederholbar:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

Auf MCP-Elicitierungsanfragen reagieren

MCP-Server können während einer Aufgabe strukturierte Eingaben von Ihnen anfordern, indem sie Elicitierung verwenden. Wenn ein Server Informationen benötigt, die er nicht selbst abrufen kann, zeigt Claude Code einen interaktiven Dialog an und leitet Ihre Antwort an den Server weiter. Auf Ihrer Seite ist keine Konfiguration erforderlich: Elicitierungsdialoge werden automatisch angezeigt, wenn ein Server sie anfordert.

Server können Eingaben auf zwei Arten anfordern:

• Formularmodus: Claude Code zeigt einen Dialog mit Formularfeldern an, die vom Server definiert werden (beispielsweise eine Aufforderung für Benutzernamen und Passwort). Füllen Sie die Felder aus und senden Sie sie ab.
• URL-Modus: Claude Code fragt, ob ein Link in Ihrem Browser geöffnet werden soll. Server verwenden diesen Modus für einen Ablauf, der außerhalb des Terminals abgeschlossen wird, z. B. für die Anmeldung.

Im URL-Modus übergibt Claude Code die URL als Befehlszeilenargument an den URL-Handler Ihres Systems und begrenzt die Länge dieses Arguments. Wenn die URL nach der Escape-Sequenz für die Befehlszeile diese Grenze überschreitet, können Sie die Anfrage nur ablehnen. Jedes Zeichen, das Escape-Sequenzen benötigt, wie % oder &, zählt vierfach zur Grenze: sein eigenes Zeichen plus drei Escape-Zeichen. Eine URL ohne diese Zeichen erreicht die Grenze bei etwa 8.000 Zeichen. Eine URL, die größtenteils aus Prozentzeichen-Escape-Sequenzen besteht, bei denen jedes dritte Zeichen ein % ist, erreicht sie bei etwa 4.000.

Um automatisch auf Elicitierungsanfragen zu reagieren, ohne einen Dialog anzuzeigen, verwenden Sie den Elicitation-Hook.

Wenn Sie einen MCP-Server erstellen, der Elicitierung verwendet, lesen Sie die MCP-Elicitierungsspezifikation für Protokolldetails und Schemabeispiele.

Bei Verbindungen, die Protokollrevision 2026-07-28 verwenden, deklariert Claude Code elicitation: {form: {}, url: {}} in seinen Client-Funktionen, sodass ein Server dort beide Modi über die Standard-Elicitierungsanfrage des Protokolls anfordern kann.

MCP-Ressourcen verwenden

MCP-Server können Ressourcen bereitstellen, auf die Sie mit @ Erwähnungen verweisen können, ähnlich wie Sie auf Dateien verweisen.

MCP-Ressourcen referenzieren

1. Verfügbare Ressourcen auflisten

Geben Sie @ in Ihre Eingabeaufforderung ein, um verfügbare Ressourcen von allen verbundenen MCP-Servern anzuzeigen. Ressourcen werden zusammen mit Dateien im Autocomplete-Menü angezeigt.

2. Eine bestimmte Ressource referenzieren

Verwenden Sie das Format @server:protocol://resource/path, um auf eine Ressource zu verweisen:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

3. Mehrere Ressourcenverweise

Sie können mehrere Ressourcen in einer einzelnen Eingabeaufforderung referenzieren:

Compare @postgres:schema://users with @docs:file://database/user-model

[!TIP]

Tipps:

• Ressourcen werden automatisch abgerufen und als Anhänge eingebunden, wenn sie referenziert werden
• Ressourcenpfade sind in der @ Erwähnungs-Autocomplete fuzzy-durchsuchbar
• Claude Code stellt automatisch Tools bereit, um MCP-Ressourcen aufzulisten und zu lesen, wenn Server diese unterstützen
• Ressourcen können jeden Inhaltstyp enthalten, den der MCP-Server bereitstellt (Text, JSON, strukturierte Daten usw.)

MCP Apps UI-Ressourcen sind Einträge mit einem ui:// URI oder dem text/html;profile=mcp-app Medientyp: Seiten für eine Host-Anwendung zum Rendern statt Inhalte für Claude zum Lesen. Sie werden nicht in den @ Vorschlägen oder in den Ergebnissen des Ressourcenlisten-Tools angezeigt, und ein Server, der nur UI-Ressourcen anbietet, zeigt eine leere Ressourcenliste an. Das Lesen einer UI-Ressource über ihren URI funktioniert dennoch.

Mit MCP-Tool-Suche skalieren

Die Tool-Suche hält die MCP-Kontextnutzung niedrig, indem Tool-Definitionen aufgeschoben werden, bis Claude sie benötigt. Nur Tool-Namen und Server-Anweisungen werden beim Sitzungsstart geladen, sodass das Hinzufügen weiterer MCP-Server minimale Auswirkungen auf Ihr Kontextfenster hat. Claude Code erzwingt keine feste Tool-Obergrenze pro Server; die praktische Grenze ist Ihr Kontextfenster-Budget.

[!NOTE]

Die Tool-Suche wird bei Microsoft Foundry Bereitstellungen auf Azure nicht unterstützt, die sie serverseitig ablehnen: Claude Code erkennt die Ablehnung und lädt MCP-Tools stattdessen vorab für diese Bereitstellung. ENABLE_TOOL_SEARCH kann dies nicht überschreiben, da die Ablehnung von der Bereitstellung selbst kommt.

Tool-Suche für MCP-Server-Autoren

Wenn Sie einen MCP-Server erstellen, wird das Feld „Server-Anweisungen“ mit aktivierter Tool-Suche nützlicher. Server-Anweisungen helfen Claude zu verstehen, wann nach Ihren Tools gesucht werden soll, ähnlich wie Skills funktionieren.

Fügen Sie klare, aussagekräftige Server-Anweisungen hinzu, die erklären:

• Welche Kategorie von Aufgaben Ihre Tools verarbeiten
• Wann Claude nach Ihren Tools suchen sollte
• Wichtige Funktionen, die Ihr Server bietet

Claude Code kürzt eine Tool-Beschreibung oder Server-Anweisungen, die diese Standardgrenzen überschreiten, und Claude sieht nur den Text vor der Kürzung:

• Server-Anweisungen und die Beschreibung eines Tools, das vorab geladen wird: 4.096 Zeichen
• Die Beschreibung eines Tools, das Claude über die Tool-Suche lädt: 16.384 Zeichen

Halten Sie Beschreibungen und Anweisungen prägnant, und platzieren Sie kritische Details am Anfang. Wenn die Tool-Suche Claudes Suchanfrage mit der Beschreibung eines Tools abgleicht, liest sie nur den Teil innerhalb der kürzeren Grenze; platzieren Sie daher auch die Begriffe, nach denen Claude suchen würde, am Anfang. Ein Tool wird vorab geladen und behält die kürzere Grenze, wann immer es nicht aufgeschoben wird, zum Beispiel wenn die Tool-Suche ausgeschaltet ist, wenn das Tool als vorab zu laden markiert ist oder wenn sein Server vom Aufschub ausgenommen ist.

Vor v2.1.296 lag die kürzere Grenze bei 2.048 Zeichen, und vor v2.1.295 galt sie für jede Tool-Beschreibung, einschließlich einer, die über die Tool-Suche geladen wurde.

Beschreibungen und Anweisungen einiger der MCP-Server, die Anthropic unter api.anthropic.com hostet, erreichen Claude vollständig. Um die Grenzen für die anderen MCP-Server in Ihrer Sitzung zu ändern, setzen Sie CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH auf eine Anzahl von Zeichen. Die von Ihnen gesetzte Zahl ersetzt beide Grenzen: 8192 beispielsweise erhöht die kürzere Grenze und senkt die längere. Diese Variable erfordert Claude Code v2.1.280 oder später.

Ein Tool vorab laden oder aufgeschoben lassen

Um zu steuern, wie eines der Tools Ihres Servers geladen wird, setzen Sie "anthropic/alwaysLoad" im _meta-Objekt dieses Tools. Die Person, die Ihren Server zu Claude Code hinzufügt, kann in ihrer Konfiguration auch alwaysLoad für den gesamten Server setzen, und deren Einstellung kann Ihre überschreiben:

Der folgende tools/list-Eintrag fordert an, dass ein Tool vorab geladen wird:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

Tool-Suche konfigurieren

Die Tool-Suche ist standardmäßig aktiviert: MCP-Tools werden aufgeschoben und bei Bedarf erkannt.

Das Setzen von CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS hält die Tool-Suche aus. Sie können sie nicht durch das Setzen von ENABLE_TOOL_SEARCH selbst überschreiben. Ab Claude Code v2.1.227 kann Ihre Organisation die Tool-Suche unter dieser Variablen über verwaltete Einstellungen aktiviert halten. In einer Sitzung, die die HIPAA-Konfiguration erhält, ist die Tool-Suche ausgeschaltet, und weder ENABLE_TOOL_SEARCH noch verwaltete Einstellungen schalten sie wieder ein. Deaktivieren Sie Pre-Release-Funktionen behandelt, wo die Überschreibung gilt und was die Variable entfernt.

Claude Code verwendet die Tool-Suche bei Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 und neueren Modellen bzw. bei Opus 4.5, Sonnet 4.5, Haiku 4.5 und neueren Modellen auf Google Clouds Agent Platform. Bei früheren Modellen lädt Claude Code alle MCP-Tools vorab, und ENABLE_TOOL_SEARCH=true überschreibt dies nicht.

Auf Google Clouds Agent Platform entscheidet Claude Code nach Modellgeneration:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 und neuere: Die Tool-Suche ist standardmäßig aktiviert, genauso wie bei der Anthropic API.
• Frühere Agent Platform-Modelle: Claude Code lädt alle MCP-Tools vorab, da ihre Serving-Stacks den erforderlichen Beta-Header ablehnen. ENABLE_TOOL_SEARCH=true überschreibt dies nicht.

Vor v2.1.221 deaktivierte Claude Code die Tool-Suche für alle Modelle auf Google Clouds Agent Platform, es sei denn, Sie setzen ENABLE_TOOL_SEARCH=true.

Steuern Sie das Verhalten der Tool-Suche mit der Umgebungsvariablen ENABLE_TOOL_SEARCH:

# Verwenden Sie einen benutzerdefinierten 5%-Schwellenwert
ENABLE_TOOL_SEARCH=auto:5 claude

# Deaktivieren Sie die Tool-Suche vollständig
ENABLE_TOOL_SEARCH=false claude

Oder setzen Sie den Wert in Ihrem settings.json env-Feld.

Sie können auch das ToolSearch-Tool spezifisch deaktivieren:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Wenn Sie ToolSearch verweigern oder es in --tools weglassen, werden MCP-Tools stattdessen vorab geladen, aber eine Anfrage kann dennoch einen Platzhalter-Eintrag defer_loading enthalten. Wenn ein Gateway diesen Eintrag ablehnt, siehe Tool-Suche über ein LLM-Gateway.

Tool-Suche über ein LLM-Gateway

[!NOTE]

Diese Fälle werden an anderer Stelle behandelt:

• Sie haben CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS gesetzt: siehe wie sich dies auf die Tool-Suche auswirkt
• Eine Anfrage ist mit einem Fehler fehlgeschlagen, der defer_loading oder tool_reference nennt: siehe Extra inputs are not permitted

Wenn ANTHROPIC_BASE_URL auf ein Gateway verweist, ist die Tool-Suche standardmäßig aktiviert, sodass Anfragen defer_loading-Tool-Felder und tool_reference-Blöcke enthalten, die das Gateway weiterleiten muss. Solange die Tool-Suche aktiviert ist, werden MCP-Tools aufgeschoben. Um stattdessen alle Tools vorab zu laden, setzen Sie ENABLE_TOOL_SEARCH=false in Ihrer Shell oder in Ihrem Einstellungsfeld env. Vor v2.1.304 war die Tool-Suche hinter einem Gateway ausgeschaltet, es sei denn, ENABLE_TOOL_SEARCH war true, auto oder auto:N.

Ab v2.1.305 kann Claude Code eine Anfrage ohne Tool-Suche erneut versuchen, nachdem ein 400 oder 422 aufgetreten ist, dessen Ursache es nicht erkennt. Wenn der Wiederholungsversuch funktioniert, wird nichts auf dem Bildschirm angezeigt, und Sie müssen nichts tun: MCP-Tools werden stattdessen vorab geladen. Claude Code versucht die Tool-Suche später erneut, auf Kosten einer weiteren abgelehnten Anfrage. Um diese Anfragen zu vermeiden, setzen Sie ENABLE_TOOL_SEARCH=false.

Tools, die unterhalb des ENABLE_TOOL_SEARCH=auto-Schwellenwerts aufgeschoben bleiben

Wenn /context Tools als (deferred) oder (loaded on-demand) kennzeichnet, obwohl ihre Definitionen insgesamt unter dem auto-Schwellenwert liegen, war die Tool-Suche in dieser Konversation bereits aktiviert und ist aktiviert geblieben. Die Summe kann später sinken, zum Beispiel während sich MCP-Server neu verbinden, nachdem Sie eine Sitzung fortgesetzt haben. Sie müssen nichts tun: Claude lädt jedes dieser Tools, wenn eine Aufgabe es benötigt.

Einen Server vom Aufschub ausnehmen

Wenn die Tools eines Servers Claude immer sichtbar sein sollten, ohne einen Suchschritt, setzen Sie alwaysLoad in der Konfiguration dieses Servers auf true. Die Tools des Servers werden dann unabhängig von der ENABLE_TOOL_SEARCH-Einstellung in den Kontext geladen. Verwenden Sie dies für eine kleine Anzahl von Tools, die Claude bei jedem Durchgang benötigt, da jedes vorab geladene Tool Kontext verbraucht, der sonst für Ihre Konversation verfügbar wäre.

Der folgende .mcp.json-Eintrag nimmt einen HTTP-Server aus, während andere Server aufgeschoben bleiben:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Das Feld alwaysLoad ist auf allen Server-Typen verfügbar.

Das Setzen von alwaysLoad: true lässt auch den Startup auf die Tools des Servers warten, begrenzt auf das Standard-5-Sekunden-Verbindungs-Timeout, da sie vorhanden sein müssen, wenn der erste Prompt erstellt wird. Ein Remote-Server mit einem gültigen cached-Eintrag liefert seine Tools aus dem Cache, ohne sich zu verbinden, sodass er den Startup nicht verzögert. Andere Server verbinden sich standardmäßig im Hintergrund; setzen Sie MCP_CONNECTION_NONBLOCKING=0, um auch auf sie zu warten.

Die Tools eines Servers aufschieben

Um alle Tools eines Servers hinter der Tool-Suche zu halten, setzen Sie "alwaysLoad": false im Eintrag dieses Servers in Ihrer MCP-Konfiguration. Das schließt Tools ein, die der Autor des Servers als vorab zu laden markiert hat. Wenn Sie alwaysLoad weglassen, werden diese markierten Tools vorab geladen. Erfordert Claude Code v2.1.287 oder später.

MCP-Prompts als Befehle verwenden

MCP-Server können Prompts bereitstellen, die als Befehle in Claude Code verfügbar werden.

Prompts von einem Server namens anthropic-skills werden nicht angezeigt, da Claude Code diesen Namen für mit claude.ai synchronisierte Skills reserviert. Die Tools des Servers funktionieren weiterhin. Benennen Sie den Server in Ihrer MCP-Konfiguration um, um seine Prompts aufzulisten.

MCP-Prompts ausführen

1. Verfügbare Prompts entdecken

Geben Sie / ein, um die Ihnen verfügbaren Befehle anzuzeigen, einschließlich derjenigen von MCP-Servern. Claude Code listet jeden MCP-Prompt als /servername:promptname (MCP) auf. Die Eingabe von /mcp__servername__promptname führt ihn ebenfalls aus.

2. Einen Prompt ohne Argumente ausführen

/mcp__github__list_prs

3. Einen Prompt mit Argumenten ausführen

Viele Prompts akzeptieren Argumente. Übergeben Sie diese durch Leerzeichen getrennt nach dem Befehl. Claude Code teilt die Argumente nach Leerzeichen auf, sodass jedes Argument ein einzelnes Token ist:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

[!TIP]

Tipps:

• MCP-Prompts werden dynamisch von verbundenen Servern erkannt
• Argumente werden basierend auf den definierten Parametern des Prompts analysiert
• Prompt-Ergebnisse werden direkt in das Gespräch eingefügt
• In der Form /mcp__servername__promptname ersetzt Claude Code alle Zeichen im Servernamen außerhalb von A-Z, a-z, 0-9, _ und - durch _ und verwendet den Prompt-Namen, wie ihn der Server deklariert

Verwaltete MCP-Konfiguration

Für Organisationen, die eine zentralisierte Kontrolle über MCP-Server benötigen, die Benutzer verbinden können, siehe Verwaltete MCP-Konfiguration. Sie behandelt die Bereitstellung eines festen Serversatzes mit managed-mcp.json, die Bereitstellung von Servern für jeden Benutzer mit managedMcpServers, die Einschränkung von Servern mit allowedMcpServers und deniedMcpServers sowie das, was Benutzer sehen, wenn ein Server blockiert ist.