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, um sich mit Remote-MCP-Servern zu verbinden. Dies ist der am weitesten unterstützte Transport für cloudbasierte Dienste.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

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

Wenn Sie MCP-Server über JSON in .mcp.json, ~/.claude.json oder claude mcp add-json konfigurieren, akzeptiert das Feld type den Wert streamable-http als Alias für http. Die MCP-Spezifikation verwendet für diesen Transport den Namen streamable-http, sodass aus der Serverdokumentation kopierte Konfigurationen ohne Änderung funktionieren.

Ein JSON-Eintrag, der eine url, aber keinen type hat, ist ein Konfigurationsfehler, weil 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, etwa eine Agent SDK-Anwendung oder die Desktop-App, kann einen In-Process-Server mit "type": "sdk" registrieren. Claude Code überspringt einen "type": "sdk"-Eintrag in .mcp.json, ~/.claude.json oder in den Einstellungen und meldet Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register.

[!NOTE]

Bei Ausführungen mit --output-format stream-json meldet Claude Code einen übersprungenen --mcp-config-Eintrag zusätzlich im Feld mcp_server_errors des system/init-Ereignisses, sodass Skripte erkennen können, dass der Server nie geladen wurde.

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

[!WARNING]

Der SSE-Transport (Server-Sent Events) ist veraltet. Verwenden Sie stattdessen HTTP-Server, sofern 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> hinzu wie einen HTTP-Server. Claude Code versucht zuerst den HTTP-Transport und wechselt zu SSE, wenn der Server ihn nicht akzeptiert. Der automatische Wechsel erfordert Claude Code v2.1.265 oder höher.

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

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
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 laufen als lokale Prozesse auf Ihrem Rechner. Sie eignen sich ideal für Tools, die direkten Systemzugriff benötigen, oder für eigene Skripte.

Claude Code setzt CLAUDE_PROJECT_DIR in der Umgebung des gestarteten Servers auf das Projektstammverzeichnis, sodass Ihr Server projektrelative Pfade auflösen kann, ohne vom Arbeitsverzeichnis abzuhängen. Dies ist dasselbe Verzeichnis, das Hooks in ihrer Variable CLAUDE_PROJECT_DIR erhalten. Lesen Sie sie innerhalb Ihres Serverprozesses aus, zum Beispiel mit 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 der Sitzung Arbeitsverzeichnisse hinzufügen oder entfernen. Ein Server, der seinen eigenen Dateisystemzugriff auf eine Menge erlaubter Verzeichnisse beschränkt, sollte stattdessen die MCP-Anfrage roots/list implementieren. Claude Code beantwortet roots/list mit dem Startverzeichnis der Sitzung sowie jedem zusätzlichen Arbeitsverzeichnis, das Sie mit --add-dir, /add-dir oder der Einstellung additionalDirectories freigegeben haben. Claude Code sendet notifications/roots/list_changed, wenn sich diese Menge ändert.

Diese Variable wird in der Umgebung des Servers gesetzt, nicht in der eigenen Umgebung von Claude Code. Wenn Sie sie daher per ${VAR}-Expansion im command oder in den args eines projektbezogenen .mcp.json-Eintrags oder eines Servereintrags mit lokalem oder Benutzer-Geltungsbereich in ~/.claude.json referenzieren, ist ein Standardwert wie ${CLAUDE_PROJECT_DIR:-.} erforderlich. Von Plugins bereitgestellte MCP-Konfigurationen ersetzen ${CLAUDE_PROJECT_DIR} direkt und benötigen keinen Standardwert.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!NOTE]

Bei stdio-Servern trennt -- (doppelter Bindestrich) die eigenen Optionen von Claude, etwa --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 oben --port, als eigene Optionen zu parsen.

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

Wie Claude Code einen stdio-Server beendet

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 auf dessen Beendigung, bevor es ihn zwangsweise stoppt. Wenn Ihr Server beim Herunterfahren Zustand speichert oder Sperrdateien entfernt, behandeln Sie das Signal für Ihre Plattform und schließen Sie innerhalb dieser Zeit ab:

• Unter macOS und Linux: Claude Code sendet SIGINT, dann SIGTERM, falls 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, falls der Prozess 300 Millisekunden später noch läuft.

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

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

WebSocket-Server halten eine persistente bidirektionale Verbindung, was sich für Remote-MCP-Server eignet, die Ereignisse unaufgefordert an Claude senden. Verwenden Sie stattdessen HTTP, wenn Ihr Server nur auf Anfragen antwortet, da HTTP OAuth und das Flag claude mcp add --transport unterstützt, WebSocket hingegen keines von beiden.

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 ausschließlich über Header. Übergeben Sie also ein statisches Token in headers oder erzeugen Sie eines beim Verbindungsaufbau mit headersHelper. Das Flag claude mcp add --transport akzeptiert ws nicht.

Einen Server aus Einrichtungsanleitungen für einen anderen Client hinzufügen

MCP-Server sind nicht spezifisch für Claude Code. Die Einrichtungsanleitung eines Servers kann daher für Claude Desktop, Cursor oder einen anderen MCP-Client geschrieben sein und keinen claude mcp add-Befehl enthalten. Um den Server trotzdem hinzuzufügen, suchen Sie in dieser Anleitung 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 läuft auf Ihrem Rechner.
• Ein mcpServers-JSON-Block: eine Konfiguration, die für die Einstellungsdatei eines anderen Clients geschrieben wurde.

Jede dieser Formen ist eine der Eingaben, die die vier Optionen unter MCP-Server installieren entgegennehmen. Suchen Sie unten die Form, die Ihnen vorliegt, um sie in den Befehl umzuwandeln, den Claude Code akzeptiert. Jeder Befehl schreibt in den lokalen Geltungsbereich, sofern Sie nicht --scope project oder --scope user hinzufügen.

Einen Server aus einer URL hinzufügen

Eine URL bedeutet, dass der Server remote ist. Fügen Sie einen https://-Endpunkt mit --transport http hinzu, oder folgen Sie Option 2, wenn die Anleitung angibt, dass der Endpunkt SSE verwendet. Verwenden Sie für einen wss://-Endpunkt stattdessen Option 4, da --transport den Wert ws nicht akzeptiert:

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

Wenn die Anleitung zusätzlich einen API-Schlüssel oder einen Token-Header angibt, ü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 läuft. Setzen Sie den gesamten Befehl hinter --, damit Claude Code Flags wie -y an den Befehl übergibt, der den Server startet, anstatt sie als eigene Optionen zu lesen. Übergeben Sie alle Umgebungsvariablen, die die Anleitung verlangt, mit --env nach dem Servernamen und vor --:

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

Option 3 behandelt das Trennzeichen -- ausführlich.

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 denselben Wrapper-Schlüssel und dieselbe Eintragsform, die Claude Code liest. Übergeben Sie an claude mcp add-json das Objekt innerhalb von mcpServers, nicht den Wrapper. Zwei Arten von Einträgen müssen zuerst korrigiert werden:

• Eine url ohne type: Fügen Sie passend zum Endpunkt "type": "http", "type": "sse" oder "type": "ws" hinzu. Claude Code liest einen Eintrag ohne type als stdio-Server, daher schlägt ein url-Eintrag ohne type fehl.
• Ein Schlüssel mit anderen Zeichen als Buchstaben, Ziffern, 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 einer JSON-Konfiguration hinzufügen behandelt das Escaping in der Shell 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 im Stammverzeichnis Ihres Projekts hinzu und committen Sie ihn. Projekt-Geltungsbereich beschreibt, wie Claude Code diese Datei lädt und genehmigt.

Jeder claude mcp add- und claude mcp add-json-Befehl gibt bei Erfolg eine Zeile Added ... aus. Um zu prüfen, ob Claude Code sich verbunden hat, führen Sie claude mcp get <name> aus. Serverstatus behandelt die angezeigten Status und den Genehmigungsschritt für .mcp.json-Server.

Ihre Server verwalten

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

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

Wenn Sie einen Remote-Server entfernen, löscht Claude Code auch die OAuth-Token und die Client-Registrierung, die es für diesen Server gespeichert hat. Claude Code widerruft die Token nicht beim Autorisierungsserver, der sie ausgestellt hat. Um die Token dort zu widerrufen, wo der Autorisierungsserver einen Widerruf unterstützt, führen Sie claude mcp logout <name> in Ihrer Shell vor claude mcp remove <name> aus.

Serverstatus

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

claude mcp list zeigt neben jedem aufgelisteten Server einen Integritätsstatus an, etwa ✔ Connected, ! Needs authentication oder ✘ Failed to connect. Ein Fehlerstatus bedeutet, dass Claude Code keine Verbindung zu diesem Server herstellen konnte, nicht dass der Listenbefehl fehlgeschlagen ist.

Die Status 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> an.
• ⊘ Disabled for this project (re-enable via /mcp): ein Server, der in der Liste disabledMcpServers des Projekts steht. Claude Code zeigt ihn sowohl in claude mcp list als auch in claude mcp get <name> an. Schalten Sie den Server über das /mcp-Panel wieder ein.
• ✘ Blocked by enterprise managed policy: ein Server, den eine der Richtlinien Ihrer Organisation ablehnt. Claude Code zeigt ihn sowohl in claude mcp list als auch in claude mcp get <name> an. Ein Server, der durch eine Allowlist, eine Denylist oder eine andere Einschränkung in der verwalteten MCP-Konfiguration blockiert wird, wird in beiden Befehlen ausgeblendet, statt mit diesem Status angezeigt zu werden. Fragen Sie Ihren Administrator, welche Richtlinie den Server blockiert.

Genehmigungen von Projektservern und Workspace-Vertrauen

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

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

• Ihre Benutzerdatei ~/.claude/settings.json
• verwaltete Einstellungen
• mit --settings übergebene Einstellungen

Claude Code wendet auch Genehmigungen aus einer nicht versionierten .claude/settings.local.json an, führt aber git aus, um zu prüfen, ob die Datei versioniert ist, und führt diese Prüfung nur in einem vertrauenswürdigen Ordner aus. In einem Ordner, dem Sie nie vertraut haben, wartet Claude Code auf den Vertrauensdialog, bevor es die Genehmigungen der Datei anwendet, es sei denn, der Ordner ist Ihr eigenes Konfigurationsverzeichnis: Ihr Home-Verzeichnis oder ein Verzeichnis, dessen .claude Sie als CLAUDE_CONFIG_DIR festgelegt haben. Vor v2.1.207 wendete Claude Code Genehmigungen aus einer nicht versionierten .claude/settings.local.json auch in einem Ordner an, dem Sie nie vertraut hatten.

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

Details zum Serverstatus

In /mcp, einschließlich des dortigen Menüs eines Servers, und im /plugin-Manager kann ein Remote-HTTP- oder SSE-Server, den Sie bereits verwendet haben, einen cached-Status wie cached 2h ago · connects on first use · 5 tools anzeigen. Claude Code hat die Tool-Liste des Servers aus seinem Discovery-Cache geladen, der in einer früheren Sitzung gespeichert wurde, statt sich beim Start zu verbinden, und Claude Code verbindet den Server, wenn Claude zum ersten Mal eines der Tools des Servers aufruft. Die Tools sind ab Ihrer ersten Nachricht verfügbar, Sie müssen also nichts tun. Der Discovery-Cache und sein cached-Status erfordern Claude Code v2.1.221 oder höher.

Der Discovery-Cache ist standardmäßig deaktiviert, sofern ihn kein schrittweiser Rollout für Ihr Konto aktiviert hat. Setzen Sie MCP_DISCOVERY_CACHE=1, um ihn einzuschalten, oder 0, um ihn auch dann ausgeschaltet zu lassen, wenn der Rollout ihn aktiviert hat. Vor v2.1.238 war der Cache standardmäßig aktiviert.

Wenn Sie im Menü eines Servers in /mcp Disable oder Clear authentication auswählen, verwirft Claude Code auch den Cache-Eintrag dieses Servers. Reconnect verwirft ihn ebenfalls bei einem verbundenen oder fehlgeschlagenen Server; bei einem cached-Server verbindet Reconnect den Server sofort und behält den Eintrag. Wenn Claude Code sich nach dem Verwerfen des Eintrags das nächste Mal mit dem Server verbindet, ruft es die Tool-Liste vom Server statt aus dem Cache ab.

Verbindungsfehler und nicht konfigurierte Server

Wenn der Status eines Servers ✘ Failed to connect lautet, hängt claude mcp list die Fehlerdetails an diese Statuszeile an, und claude mcp get <name> zeigt sie in einer Issue:-Zeile an. Die Details bestehen aus dem HTTP-Status oder Fehlercode sowie etwaigem Fehlertext, den der Server zurückgegeben hat. Die Detailansicht des Servers in /mcp enthält denselben vom Server gemeldeten Text in ihrer Issue:-Zeile.

Claude Code schwärzt anmeldedatenähnlichen Text in diesen Details und fügt nie die expandierte Server-URL ein, die Geheimnisse enthalten kann. Claude Code hängt an einen ✘ Connection error-Status keine Details an, weil der dort ausgegebene Ausnahmetext diese URL enthalten kann.

Wenn Sie die Authentifizierung über /mcp abschließen und die Verbindung trotzdem mit einem HTTP-Status oder einem Transportfehlercode fehlschlägt, fügt Claude Code diesen Code und den Ursprung der Server-URL in die Meldung ein, die es nach dem Versuch ausgibt. Der Ursprung besteht aus Schema und Host sowie dem Port, falls die URL einen angibt, etwa https://mcp.example.com.

• Pfad und Query erscheinen nie in dieser Meldung.
• Bei einem Server im lokalen, Projekt- oder Benutzer-Geltungsbereich oder in der verwalteten MCP-Konfiguration zeigt der Ursprung den Host so, wie er in dieser Konfiguration geschrieben ist, sodass eine ${VAR}-Referenz im Host in der Meldung nicht expandiert wird.
• Bei einem Fehler ohne Status oder Fehlercode zeigt Claude Code den Fehlertext ohne den Ursprung an.

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 mit ihm zu verbinden. Ein Plugin kann einen solchen Platzhaltereintrag für einen Konnektor enthalten, den Sie später konfigurieren, sodass Claude Code ihn nicht als Fehler oder Einrichtungsproblem meldet. Die Detailansicht des Servers in /mcp lautet 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 beschreibt, was Claude Code prüft und wie Sie die Warnung beseitigen:

• Versteckte Leerzeichen: Claude Code warnt, wenn ein MCP-Konfigurationswert versteckte führende oder nachgestellte Leerzeichen enthält, was oft vom Einfügen eines Tokens mit einem nachgestellten Zeilenumbruch herrührt. Claude Code prüft command, url, jeden args-Eintrag sowie die Werte und Schlüsselnamen unter env und headers. Claude Code zeigt die Warnung in der Ausgabe von claude mcp list und in /mcp an und nennt die betroffenen Felder, ohne ihre Werte wiederzugeben, zum Beispiel Leading or trailing whitespace in: headers.Authorization. Claude Code entfernt die Leerzeichen nicht und verwendet die Werte genau wie geschrieben. Bearbeiten Sie daher die Konfiguration, um sie zu entfernen.
• Gleicher Name in mehr als einem Geltungsbereich: Wenn Sie denselben Servernamen in mehr als einem Geltungsbereich mit unterschiedlichen Endpunkten definieren, warnt Claude Code in der Ausgabe von claude mcp list und in /mcp vor dem Konflikt. Claude Code speichert OAuth-Anmeldungen pro Endpunkt. Wenn Sie also die Definition authentifizieren, die in einem Projekt geladen wird, müssen Sie sich in einem Projekt, in dem eine andere Definition geladen wird, dennoch separat anmelden. Behalten Sie den gewünschten Endpunkt und entfernen Sie die anderen mit claude mcp remove <name> --scope <scope>. In der Warnung zitiert Claude Code den Endpunkt jedes Geltungsbereichs so, wie er in Ihrer Konfiguration geschrieben ist, mit nicht expandierten ${VAR}-Referenzen, sodass es nie einen aufgelösten Wert wie einen API-Schlüssel anzeigt.
• Reservierte Namen: Claude Code reserviert die Namen seiner integrierten Server, darunter 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 bezeichnen beide den integrierten Server, den der Vorschaubereich 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 Ausgabe von claude mcp list und in /mcp unter Nennung der Variable und lädt den Server trotzdem mit dem nicht expandierten ${VAR}-Text. Setzen Sie die Variable oder fügen Sie einen ${VAR:-default}-Fallback hinzu. In url und headers eines Remote-Servers werden einige Anmeldedaten-Variablen stattdessen ohne Warnung als leer gelesen.

Verfügbarkeit von Tools

Das /mcp-Panel zeigt neben jedem verbundenen Server die Anzahl der Tools an und kennzeichnet Server, die die Tools-Fähigkeit ankündigen, aber keine Tools bereitstellen.

Tool-Anzahlen in einer Cloud-Sitzung

In einer Cloud-Sitzung bedeutet eine Anzeige wie 3 of 13 tools available, dass Claude die anderen 10 nicht verwenden kann. Prüfen Sie unter anderem diese Ursachen:

• Eine Deny-Regel in der .claude/settings.json Ihres Repositorys nennt das Tool oder seinen gesamten Server: Entfernen Sie die Regel, sofern Ihre Sitzung diese Datei liest
• Der vollständige Name des Tools ist länger als 128 Zeichen: Folgen Sie den Schritten für einen zu langen Namen
• Der Server listet das Tool für seine eigene Oberfläche und nicht für Claude auf: Wenn Sie den Server pflegen, fügen Sie model zu _meta.ui.visibility des Tools hinzu, um Claude das Tool zu geben. Andernfalls gibt es nichts zu beheben.

Tools von einem Server, der sich noch verbindet

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

• Mit Tool-Suche, der Standardeinstellung: Das Warten findet innerhalb des ToolSearch-Aufrufs statt.
• Ohne Tool-Suche: Claude verwendet stattdessen das Tool WaitForMcpServers. Zu den Konfigurationen ohne Tool-Suche gehören ENABLE_TOOL_SEARCH=false und ein Modell, das älter ist als Claude Opus 4.5, Claude Sonnet 4.5 und Claude Haiku 4.5, auf der Agent Platform von Google Cloud. Für ein ANTHROPIC_BASE_URL-Gateway siehe Tool-Suche über ein LLM-Gateway.
• Bei einem Microsoft Foundry-Deployment, das auf Azure gehostet wird: Claude startet auf dem Tool-Suche-Pfad statt mit WaitForMcpServers, da Claude Code die serverseitige Ablehnung des Deployments erst über die API feststellt. Nachdem Claude Code dieses Deployment auf vorab geladene Tools umgestellt hat, werden Tools von einem Server, der seine Verbindung abschließt, bei Claudes nächster Anfrage verfügbar.

Wenn die Tool-Suche aktiviert ist und ein Server seine Verbindung abschließt, während Claude arbeitet, listet Claude Code Claude die Tool-Namen des Servers bei seiner nächsten Anfrage im selben Turn auf. Claude kann diese Tools dann 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 sich der MCP-Server des Tools noch verbindet. Solange sich der Server im ersten Verbindungsversuch befindet, hält Claude Code den Aufruf bis zu 10 Sekunden zurück und führt ihn aus, sobald das Tool verfügbar ist. Wenn sich der Server nicht rechtzeitig verbindet oder 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, damit Claude Code sich nicht mehr mit ihm verbindet, ohne dass seine Konfiguration verloren geht. Claude Code listet den Server weiterhin in /mcp auf, als deaktiviert gekennzeichnet.

Wenn Sie einen Server umschalten, speichert Claude Code Ihre Wahl pro Projekt in ~/.claude.json, in einer von zwei Listen, die disjunkte Mengen von Servern abdecken:

• disabledMcpServers: eine Opt-out-Liste für benutzerkonfigurierte Server, Plugin-Server, Server, die Ihre Organisation über verwaltete Einstellungen bereitstellt, die claude.ai-Konnektoren, die Claude Code selbst abruft, sowie integrierte Server, die standardmäßig eingeschaltet sind. Claude Code verbindet sich nicht mit einem Server, den Sie hier aufführen. Wenn Sie einen claude.ai-Konnektor mit dem projektbezogenen /mcp-Schalter deaktivieren, der unter claude.ai-Konnektoren 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 ausgeschaltet sind, etwa computer-use. Claude Code verbindet sich mit einem standardmäßig ausgeschalteten Server nur, wenn Sie ihn hier aufführen.

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

disabledMcpServers und enabledMcpServers haben nichts mit enabledMcpjsonServers und disabledMcpjsonServers zu tun, die die Genehmigung von Servern steuern, die in der .mcp.json-Datei eines Projekts definiert sind.

MCP-Client-Laufzeitumgebungen

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

Claude Code wählt bei jedem Start eine Laufzeitumgebung und behält sie bis zum Beenden bei. In Sitzungen, in denen es Feature-Flags abruft, verwendet es ab Claude Code v2.1.232 die v2-Laufzeitumgebung.

In den Sitzungen, in denen es keine Feature-Flags abruft, verwendet Claude Code ab Claude Code v2.1.274 standardmäßig die v2-Laufzeitumgebung:

• Sitzungen auf Amazon Bedrock, Claude Platform on AWS, der Agent Platform von Google Cloud oder Microsoft Foundry, sofern nicht eine Host-Plattform, die Claude Code einbettet, CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST setzt
• Sitzungen, die über ein Claude Apps Gateway angemeldet sind
• Sitzungen, in denen Sie Telemetrie oder das Abrufen von Feature-Flags ausschalten, zum Beispiel mit DISABLE_TELEMETRY

Unter v2 verhält sich Claude Code außerdem wie folgt:

• Es fragt HTTP-, stdio- und claude.ai-Konnektor-Server, ob sie die neuere Revision unterstützen, und verwendet sie mit den Servern, die dies tun. Dazu gehören die Konnektoren von Cloud- und Remote Control-Sitzungen. Mit allen anderen Servern verbindet sich Claude Code wie unter v1.
• Es empfängt list_changed-Benachrichtigungen von Servern mit der neueren Revision über einen Stream, den es offen hält.
• Es registriert keinen Channel-Server, der sich mit der neueren Revision verbindet, da diese Revision keine Channel-Nachrichten übertragen 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 unter localhost, 127.0.0.1 oder ::1 bereitgestellt wird. Die Anmeldung schlägt bei einem Server fehl, dessen Token-Endpunkt an anderer Stelle einfaches http:// ist, etwa 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, beim früheren Protokoll oder außerhalb dieses Streams halten. Um die Laufzeitumgebung selbst zu wählen, setzen Sie MCP_SDK_GENERATION auf v1 oder v2.

Um festzulegen, ob Claude Code Server nach der neueren Revision fragt, setzen Sie MCP_PROTOCOL_NEGOTIATION auf auto oder legacy. Ist diese Variable nicht gesetzt, kann Claude Code die Nachfrage bei einem stdio-Server für 7 Tage überspringen, zum Beispiel nachdem sich der Server bei der Nachfrage beendet hat. Damit ein aktualisierter Server früher gefragt wird, setzen Sie auto.

Dynamische Tool-Aktualisierungen

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

• In einer interaktiven Terminal-Sitzung ruft Claude Code die aktualisierte Liste von diesem Server ab, sodass Sie ihn nicht neu 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 ermittelten Tools, Prompts und Ressourcen des Servers bei, bis eine spätere Aktualisierung erfolgreich ist.

Benachrichtigungs-Streams in der v2-Laufzeitumgebung

In der v2-Laufzeitumgebung empfängt Claude Code list_changed-Benachrichtigungen von einem Server mit der neueren Protokollrevision über einen Stream, den es offen hält. Wenn der Stream geschlossen wird, öffnet Claude Code ihn erneut, mit zwei Einschränkungen:

• Der Stream schließt sich innerhalb von 10 Sekunden erneut: Claude Code öffnet ihn bis zu dreimal erneut und hört dann für diese Verbindung auf.
• Der Stream bleibt länger als 10 Sekunden offen und schließt sich dann, wie es bei Streams zu Serverless-Hosts häufig der Fall ist: Nach fünf erneuten Öffnungen innerhalb einer Stunde wartet Claude Code etwa sechs Stunden bis zur nächsten.

Bis der Stream wieder geöffnet wird, behalten Sie die zuletzt abgerufenen Tools, Prompts und Ressourcen des Servers. Um seine Änderungen früher zu übernehmen, verbinden Sie den Server über /mcp neu.

Automatische Wiederverbindung

Claude Code verbindet einen Remote-Server, dessen Verbindung während der Sitzung abbricht, erneut und versucht den ersten Verbindungsaufbau eines HTTP- oder SSE-Servers nach einem vorübergehenden Fehler erneut. Für einen stdio-Server siehe Stdio-Server, die sich beenden oder nicht starten.

Verbindungsabbrüche eines Remote-Servers während der Sitzung

Claude Code versucht zunächst bis zu fünfmal, einen abgebrochenen Remote-Server mit exponentiellem Backoff neu 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 die Verbindung wiederherstellt. Nach fünf fehlgeschlagenen Versuchen markiert Claude Code den Server als fehlgeschlagen oder als authentifizierungsbedürftig, wenn der Server eine erneute Autorisierung benötigt. Wenn es den Server als fehlgeschlagen markiert, sehen Sie eine Benachrichtigung MCP server "<name>" disconnected · open /mcp to reconnect. Sie können es über /mcp manuell erneut versuchen.
• Bei claude -p-Ausführungen und Agent SDK-Sitzungen: Claude Code unternimmt dieselben fünf Versuche, ohne ein /mcp-Panel, das sie anzeigt. Wenn alle fünf fehlschlagen, läuft die Ausführung ohne die Tools des Servers weiter:
  • Nach einem vorübergehenden Fehler, etwa einer 5xx-Antwort oder einer Zeitüberschreitung: Claude Code versucht einen HTTP- oder SSE-Server im Hintergrund weiterhin erneut. 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 neu verbinden. Um ihn in claude -p neu zu verbinden, starten Sie die Ausführung erneut.
  • Wenn der Server eine erneute Anmeldung erfordert: Claude Code stellt die Wiederholungsversuche ein, und eine Agent SDK-Sitzung meldet den Status des Servers als needs-auth. Melden Sie sich mit claude mcp login <name> in Ihrer Shell an. Starten Sie dann die Ausführung erneut oder verbinden Sie den Server in einer Agent SDK-Sitzung stattdessen neu.

Fehlgeschlagene erste Verbindungen

Wenn der erste Verbindungsaufbau eines HTTP- oder SSE-Servers mit einem vorübergehenden Fehler fehlschlägt, etwa einer 5xx-Antwort, einer abgelehnten Verbindung oder einer Zeitüberschreitung, versucht Claude Code es bis zu dreimal erneut. Wenn die Verbindung weiterhin fehlschlägt, markiert Claude Code den Server als fehlgeschlagen.

Diese Wiederholungsversuche gelten in folgenden Fällen nicht:

• Der erste Verbindungsaufbau eines stdio-Servers. Um es erneut zu versuchen, siehe Stdio-Server, die sich beenden oder nicht starten
• Der erste Verbindungsaufbau eines WebSocket-Servers. Um es in einer interaktiven Terminal-Sitzung erneut zu versuchen, wählen Sie im Menü des Servers in /mcp die Option Reconnect
• Ein Authentifizierungs- oder Not-found-Fehler, da zur Behebung eine Konfigurationsänderung nötig ist. 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 neu ausführt und so neue Anmeldedaten erhalten kann

Stdio-Server, die sich beenden oder nicht starten

Um einen stdio-Server erneut zu starten, lesen Sie die Spalte, die dem entspricht, was mit ihm passiert ist. Finden Sie Ihre Zeile danach, wie Sie Claude Code ausführen: eine interaktive Sitzung, eine claude -p-Ausführung oder eine Agent SDK-Sitzung.

Fehlgeschlagene Discovery-Anfragen

Nachdem ein Server verbunden ist, sendet Claude Code ihm Anfragen zur Ermittlung der Fähigkeiten, etwa tools/list, prompts/list und resources/list. Claude Code wiederholt diese Anfragen nach einem vorübergehenden Netzwerk- oder Serverfehler bis zu dreimal mit kurzem Backoff. Authentifizierungsfehler, 4xx-Antworten oder Zeitüberschreitungen von Anfragen werden nicht erneut versucht.

Fehlgeschlagene Server selbst erneut versuchen

Um jeden Server erneut zu versuchen, der fehlgeschlagen ist oder eine Authentifizierung benötigt, führen Sie /mcp reconnect all an der Claude Code-Eingabeaufforderung in einer interaktiven Terminal-Sitzung aus. Dies erfordert Claude Code v2.1.284 oder höher. Frühere 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 herstellen konnte, hängt von der Tool-Suche ab, die standardmäßig aktiviert ist:

• Mit Tool-Suche teilt Claude Code Claude mit, welcher Server fehlgeschlagen ist und welchen Verbindungsfehler er hat, sodass Claude den Verbindungsfehler in seiner Antwort meldet. Claude Code fügt dieselben Informationen in ToolSearch-Ergebnisse ein, die kein passendes Tool finden.
• In jeder Konfiguration ohne Tool-Suche meldet Claude Code fehlgeschlagene Serververbindungen nicht an Claude.

Nachrichten mit Channels pushen

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

In der v2-Laufzeitumgebung kann ein Channel-Server, der die MCP-Protokollrevision 2026-07-28 aushandelt, keine Channel-Nachrichten zustellen, daher registriert Claude Code ihn nicht als Channel. Ein Channel-Server, der diese Revision nicht unterstützt, verbindet sich mit dem früheren Handshake und wird wie bisher registriert.

Claude Code fragt stdio-Server standardmäßig nach dieser Revision. Um einen stdio-Channel-Server beim früheren Handshake zu halten, setzen Sie MCP_PROTOCOL_NEGOTIATION auf legacy, was jeden Server dabei hält.

[!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: über die Datei .mcp.json mit allen im Projekt geteilt
  • user: für Sie in allen Projekten 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 Start-Timeout für MCP-Server mit der Umgebungsvariable MCP_TIMEOUT (zum Beispiel setzt MCP_TIMEOUT=10000 claude einen Timeout von 10 Sekunden)
• Legen Sie einen Timeout für die Tool-Ausführung pro Server fest, indem Sie dem .mcp.json-Eintrag dieses Servers ein Feld timeout in Millisekunden 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 Ausgabe eines MCP-Tools 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. Der Warnschwellenwert 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-Ausgabelimits und -Warnungen
• Verwenden Sie /mcp, um sich bei Remote-Servern zu authentifizieren, die eine OAuth-2.0-Authentifizierung erfordern

Zeitlimits für MCP-Tool-Aufrufe

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

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

Der serverspezifische timeout ist ein hartes Echtzeitlimit pro Tool-Aufruf, und Fortschrittsbenachrichtigungen des Servers verlängern ihn nicht. Werte unter 1000 werden ignoriert und fallen auf MCP_TOOL_TIMEOUT zurück, oder auf dessen Standardwert von etwa 28 Stunden, wenn diese Variable nicht gesetzt ist. Für einen HTTP-, SSE- oder claude.ai-Konnektor-Server gibt es zusätzlich einen zweiten Timer pro Anfrage, 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 für den Server geltenden Tool-Timeout und MCP_TIMEOUT. Der 28-Stunden-Standardwert eines nicht gesetzten MCP_TOOL_TIMEOUT fließt nicht in diesen Vergleich ein, und ein Wert unter 60 Sekunden verkürzt den Timer nicht. Stdio- und WebSocket-Server haben keinen Timer pro Anfrage.

Ein serverspezifischer timeout von mindestens 1000 wirkt außerdem als Untergrenze für den unten beschriebenen Leerlauf-Timeout: Claude Code bricht die Tool-Aufrufe dieses Servers nie früher wegen Leerlaufs ab als nach dem serverspezifischen timeout.

Ein Tool-Aufruf an einen MCP-Server, der während des Leerlauffensters weder eine Antwort noch eine Fortschrittsbenachrichtigung sendet, wird mit einem Fehler abgebrochen, statt auf das Echtzeitlimit zu warten. Der Leerlauf-Timeout gilt für jeden Servertyp außer IDE-Servern und SDK-In-Process-Servern. Das Leerlauffenster beträgt standardmäßig fünf Minuten für HTTP-, SSE-, WebSocket- und claude.ai-Konnektor-Server und 30 Minuten für stdio-Server.

Setzen Sie die Umgebungsvariable CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in Millisekunden, um das Leerlauffenster zu ändern, oder setzen Sie sie auf 0, um die Prü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 in eine Hintergrundaufgabe verschoben. Siehe Automatisches Verschieben langer Tool-Aufrufe in den Hintergrund.

Automatisches Verschieben langer Tool-Aufrufe in den Hintergrund

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

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

Die Aufgabe erscheint in /tasks, wo Sie sie auch stoppen können, und sie überdauert das Beenden der Sitzung nicht. Der Eintrag der Aufgabe zeigt den zuletzt vom Server gemeldeten Fortschritt. 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 aufhört: Er hat möglicherweise bereits einen Teil der Arbeit erledigt oder beendet sie noch.

Die Limits pro Aufruf gelten weiterhin, während der Aufruf im Hintergrund läuft: das durch den serverspezifischen timeout oder MCP_TOOL_TIMEOUT festgelegte Echtzeitlimit und der durch CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT festgelegte Leerlauf-Timeout.

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 in den Hintergrund auszuschalten. Mit 0 wartet Claude in einer interaktiven Sitzung außerdem auf MCP-Aufgaben
• Setzen Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1, um das automatische Verschieben in den Hintergrund und Hintergrundbefehle auszuschalten

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, sofern CLAUDE_AUTO_BACKGROUND_TASKS nicht auf 1 gesetzt ist, da eine einmalige Ausführung enden kann, bevor das Ergebnis eintrifft

Ein Aufruf, der auf einen offenen Elicitation-Dialog wartet, wird nicht in den Hintergrund verschoben, solange der Dialog geöffnet ist; der Server wartet auf Ihre Eingabe und ist nicht langsam, daher verschiebt Claude Code den Wechsel, bis der Dialog geschlossen wird.

MCP-Aufgaben, die auf dem Server laufen

Eine MCP-Aufgabe ist ein langer Job, etwa ein Berichtsexport oder ein Build, den ein MCP-Server selbst mithilfe der MCP-Tasks-Erweiterung ausführt. Claudes Tool-Aufruf kehrt zurück, sobald der Server den Job annimmt, sodass Claude weiterarbeitet, sofern Sie Claude nicht warten lassen. Wenn der Job 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 die Aufgabe, indem es ihren Status beim Server abfragt. Eine Aufgabe auf einem Remote-Server läuft nach dem Beenden weiter. Um sie erneut zu verfolgen, setzen Sie dieselbe Sitzung fort.

[!NOTE]

MCP-Aufgaben 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 einer MCP-Aufgabe zu werden listet die Sitzungen und Server auf, die sie erhalten.

Eine MCP-Aufgabe stoppen oder ihr Ergebnis abrufen

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

Wenn die Aufgabe 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 beim Eintreffen des Ergebnisses untätig ist, beginnt Claude unaufgefordert damit.

Eine Frage einer MCP-Aufgabe beantworten

Eine laufende Aufgabe kann einen Elicitation-Dialog öffnen, um Sie um 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 die Aufgabe weiterläuft.

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

Beenden, Leeren oder Fortsetzen, während eine MCP-Aufgabe läuft

Eine Aufgabe auf einem Remote-Server läuft nach dem Beenden weiter. Der Prozess eines stdio-Servers stoppt, wenn Claude Code beendet wird, obwohl seine Aufgaben 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 Aufgaben zuerst abschließen oder stoppen Sie sie in /tasks.

Was ein Aufruf benötigt, um zu einer MCP-Aufgabe zu werden

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

• Der Server unterstützt Aufgaben
• 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 mit ausgeschalteter Telemetrie oder ausgeschaltetem Abrufen von Flags
• Anthropic hat MCP-Aufgaben 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, etwa die VS Code-Erweiterung und die Desktop-App, haben keine MCP-Aufgaben
• 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 einfacher 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-Aufgaben wartet. Eine einmalige claude -p "<prompt>"-Ausführung erhält keine MCP-Aufgaben.

Statusmeldungen zu einer MCP-Aufgabe

Diese Meldungen im /tasks-Eintrag einer Aufgabe oder in ihrer abschließenden Transkriptzeile bedeuten, dass Claude Code den Server oder die Aufgabe nicht erreichen kann. Solange eine davon in /tasks angezeigt wird, läuft der Job möglicherweise noch: Claude Code lässt ihn in Ruhe und prüft weiter. Die 300s- und Konfigurationsmeldungen bleiben auch nach wiederhergestelltem Kontakt am Eintrag stehen.

Zeitlimits für MCP-Aufgaben

Standardmäßig hat eine Aufgabe 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 der Aufgabe beantwortet. Wenn Sie Claude warten lassen, gelten sie für die gesamte Aufgabe. Beantwortete Statusprüfungen zählen als Aktivität für den Leerlauf-Timeout.

Claude auf das Ergebnis einer MCP-Aufgabe warten lassen

Um Claude in einer interaktiven Sitzung auf das Ergebnis einer Aufgabe warten zu lassen, 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 einer Aufgabe. Solange das automatische Verschieben in den Hintergrund aktiviert ist, wird der Aufruf standardmäßig nach zwei Minuten verschoben, sodass kurze Aufgaben an Ort und Stelle abgeschlossen werden und lange Sie nicht blockieren. Der verschobene Aufruf ist ein einfacher Hintergrundaufruf und keine MCP-Aufgabe. 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, die Aufgabe abzubrechen.

Wenn Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1 setzen oder im Bare-Modus starten, lässt das allein Claude nicht auf MCP-Aufgaben 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-Aufgaben für Serverautoren

Wenn Sie einen MCP-Server entwickeln, können Sie einen lang laufenden tools/call mit einer Aufgabe beantworten. Die MCP-Tasks-Erweiterung definiert die Nachrichten, die Sie senden. Bei einer Verbindung über die Protokollrevision 2026-07-28 enthält 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 keine Aufgabe werden kann, lässt diese Erweiterung weg.

Den Aufruf mit einer Aufgabe beantworten

Antworten Sie nur dann mit einer Aufgabe, wenn die Anfrage die Erweiterung enthält, andernfalls schlägt der Aufruf mit dem Tool-Fehler Unsupported result type 'task' for tools/call fehl. Der Aufruf schlägt ebenso fehl, wenn Ihre Antwort keine taskId oder keinen gültigen status hat. Das Aufgabenobjekt 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
}

Claude Code akzeptiert eine Aufgabenantwort, die createdAt, lastUpdatedAt oder ttlMs weglässt oder pollIntervalMs auf null setzt. Vor v2.1.317 schlug der Aufruf stattdessen mit dem Fehler Unsupported result type fehl. Um auch mit diesen Versionen zu funktionieren, senden Sie die drei Felder, die die Tasks-Erweiterung verlangt, und senden Sie pollIntervalMs als Zahl oder gar nicht.

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

Status, Ergebnisse und Fragen melden

Direkt nach der Aufgabenantwort sendet Claude Code tasks/get mit { "taskId": ... } und wiederholt dies 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.

So funktionieren Plugin-MCP-Server:

• Plugins definieren MCP-Server in .mcp.json im Stammverzeichnis des Plugins oder inline in plugin.json
• Wenn Sie ein Plugin aktivieren, startet Claude Code dessen MCP-Server automatisch
• Claude Code bietet Plugin-MCP-Tools neben manuell konfigurierten MCP-Tools 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 dennoch ausschalten, wodurch Claude Code keine Verbindung mehr zu ihm herstellt, ohne dass das Plugin entfernt wird

Beispiel für eine Plugin-MCP-Konfiguration:

In .mcp.json im Stammverzeichnis des Plugins:

{
  "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"]
    }
  }
}

Plugin-MCP-Funktionen:

• Automatischer Lebenszyklus: Server verbinden und trennen sich zu folgenden Zeitpunkten:
  • Beim Start der Sitzung verbindet Claude Code die Server aktivierter Plugins automatisch. In /mcp kann ein Remote-Plugin-Server (HTTP oder SSE), den Sie bereits verwendet haben, stattdessen den Status cached anzeigen; Claude Code verbindet ihn, wenn Claude zum ersten Mal eines seiner Tools aufruft. Wenn die Verbindung eines stdio-Plugin-Servers vor weniger als 15 Minuten fehlgeschlagen ist, überspringt Claude Code die Verbindung
  • Wenn Sie während einer Sitzung ein Plugin aktivieren oder deaktivieren, verbindet oder trennt Claude Code dessen MCP-Server, sobald die Änderung wirksam wird. Wann das der Fall ist, beschreibt Plugin-Änderungen ohne Neustart anwenden. In einer Sitzung ohne interaktives Terminal verbindet oder trennt /reload-plugins keine Plugin-MCP-Server; diese Änderungen werden in Ihrer nächsten Sitzung wirksam
  • Beim Neuladen behält Claude Code die aktiven Verbindungen von Plugin-Servern bei, deren Konfiguration unverändert ist, und verfährt ebenso, wenn Sie die MCP-Serverliste der Sitzung ersetzen, ohne diese Server über das Agent SDK zu benennen
  • Wenn Sie ab v2.1.246 die Sitzung mit /cd verschieben, verbindet Claude Code die Server der Plugins, die durch die Einstellungen des neuen Verzeichnisses aktiviert werden, und trennt die Server der Plugins, die nicht mehr aktiviert sind, sodass Sie nach dem Verschieben nicht /reload-plugins ausführen müssen
  • In Cloud-Sitzungen startet ein MCP-Aufruf an einen noch nicht verbundenen Plugin-Server, etwa direkt nach dem Aufwachen einer inaktiven Sitzung, den Server bei Bedarf und wartet, bis er verbunden ist
• Pfad-Platzhalter: ${CLAUDE_PLUGIN_ROOT} wird zum Installationsverzeichnis des Plugins aufgelöst, ${CLAUDE_PLUGIN_DATA} zu dessen Verzeichnis für persistenten Zustand und ${CLAUDE_PROJECT_DIR} zum stabilen Projektstammverzeichnis. Die Ersetzung gilt für:
  • stdio-Server: command, args, env
  • http-, sse- und ws-Server: url, headers und headersHelper
• Zugriff auf die Benutzerumgebung: Zugriff auf dieselben Umgebungsvariablen wie bei manuell konfigurierten Servern
• Mehrere Transportarten: Unterstützung für stdio-, SSE-, HTTP- und WebSocket-Transporte, wobei die Transportunterstützung je nach Server variieren kann

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

claude mcp get verbirgt die für den stdio- oder WebSocket-Server eines Plugins konfigurierten Werte, da diese Anmeldedaten enthalten können:

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

Um zu sehen, was das Plugin konfiguriert hat, suchen Sie das Plugin auf dem Datenträger und lesen Sie dessen .mcp.json oder plugin.json.

Namen von Plugin-MCP-Tools:

Tools aus einem in einem Plugin gebündelten MCP-Server enthalten in ihrem aufrufbaren Namen sowohl den Plugin-Namen als auch den Serverschlüssel. Die vollständige Form lautet 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 Server database-tools, der in einem Plugin namens my-plugin gebündelt ist, ist ein Tool query aufrufbar als:

mcp__plugin_my-plugin_database-tools__query

Verwenden Sie diesen vollständigen Namen, wenn Sie das Tool in Berechtigungsregeln, in der allowed-tools-Liste eines Skills, im Feld tools eines Subagenten oder in einem Hook-Matcher referenzieren. Ein Hook-Matcher, der gegen den bloßen Serverschlüssel geschrieben ist, etwa mcp__database-tools__.*, wird bei einem in einem Plugin gebündelten Server nie ausgelöst.

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

Details zum Bündeln von MCP-Servern mit Plugins finden Sie in der Referenz zu Plugin-Komponenten.

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.

Sie können in einem command-, args-, env-, url- oder headers-Wert eines Servers auf eine Umgebungsvariable verweisen, und zwar in einer von zwei Formen:

• ${VAR}: erweitert sich zum Wert der Umgebungsvariablen VAR
• ${VAR:-default}: wird zum Wert von VAR erweitert, wenn VAR gesetzt ist, oder zu default, wenn sie nicht gesetzt ist

Beispiel mit Variablenerweiterung

In diesem Server-Eintrag ist die URL der Wert von API_BASE_URL gefolgt von /mcp, mit https://api.example.com als Standard, und der API-Schlüssel stammt aus API_KEY:

{
  "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.

Auf eine leere Zeichenfolge gesetzte Variablen

Wenn Sie eine Variable auf eine leere Zeichenfolge setzen, gilt sie als gesetzt, sodass eine ${VAR:-default}-Referenz zur leeren Zeichenfolge statt zu default erweitert wird. Wenn Sie beim Beispielserver API_BASE_URL auf eine leere Zeichenfolge setzen, wird seine url zu /mcp, und claude mcp list meldet 'url' is not a valid URL. Um den Standard zu verwenden, heben Sie die Variable auf, statt sie auf eine leere Zeichenfolge zu setzen.

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, verbindet sich Claude Code mit oder ohne neues Token erneut:

• Ihre gespeicherte Anmeldung hat ein Refresh-Token: Claude Code aktualisiert das Token, verbindet sich erneut und wiederholt die Anfrage einmal. Der Server wird in /mcp nur gekennzeichnet, wenn dieser Wiederholungsversuch auch fehlschlägt.
• Ihre gespeicherte Anmeldung hat kein Refresh-Token: Claude Code verbindet sich einmal ohne das Token. Wenn der Server antwortet, funktionieren seine Tools, während Sie abgemeldet sind, und das abgelehnte Token wird gelöscht. Wenn der Server auch diese Verbindung ablehnt, zeigt /mcp an, dass der Server Authentifizierung benötigt.

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, 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.

[tab] 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

[tab] 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

[tab] 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}}'

[tab] 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 OAuth mit einem Server hinter einem authentifizierenden Proxy

Wenn Ihr MCP-Server OAuth hinter einem Proxy oder Gateway verwendet, das einen eigenen Header prüft, schlägt die Anmeldung fehl, wenn die OAuth-Anfragen ohne diesen Header eintreffen. Die Anmeldung über den Proxy erfordert Claude Code v2.1.299 oder höher, wobei sowohl der Header als auch die Anmeldung konfiguriert sein müssen:

• Der Header des Proxys: Übergeben Sie ihn mit --header, dem Feld headers oder einem headersHelper, unter dem Namen, den der Proxy liest
• Die OAuth-Anmeldung: Halten Sie Authorization aus den konfigurierten Headern heraus und melden Sie sich dann mit claude mcp login <name> in Ihrer Shell an. Wenn Sie einen Authorization-Header konfigurieren, verwendet Claude Code ihn als Anmeldedaten des Servers und greift für diesen Server nicht auf OAuth zurück.

Verwenden Sie dynamische Header für benutzerdefinierte Authentifizierung

Wenn eine Authentifizierung wie Kerberos, kurzlebige Token oder ein internes SSO Header benötigt, die zur Verbindungszeit generiert werden, setzen Sie headersHelper des Servers auf einen Befehl. Claude Code führt ihn beim Verbinden aus und führt seine Ausgabe mit den Headern zusammen, die es sendet. Dieses Beispiel verwendet ein Skript:

{
  "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

[!NOTE]

Wenn Ihre Sitzung mit einem 400-Fehler fehlschlägt, der ein Tool nach seiner Position benennt, folgen Sie den Schritten unter Tool input schema is invalid.

Wenn eines der Tools Ihres MCP-Servers ein Eingabeschema hat, das gegen eine der beiden Regeln verstößt, die die API durchsetzt, schließt Claude Code dieses Tool aus. Die anderen Tools des Servers sind davon nicht betroffen. Claude Code prüft beide Regeln, wenn es die Tools des Servers lädt:

• 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.

Wenn das Abrufen von Feature-Flags deaktiviert ist oder die Flags nie angekommen sind, z. B. auf einem isolierten Computer, wird ein Tool, das gegen eine Regel verstößt, nicht ausgeschlossen:

• Claude erhält das Tool unverändert, und das Log des Servers zeichnet dafür input schema would be rejected by the Anthropic API auf
• Wenn die API das Schema anschließend ablehnt, lesen Sie Tools, deren Eingabeschema die API ablehnt

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, deren Eingabeschema die API ablehnt

Wenn eine Zeile im Debug-Log the API refused this tool's input schema enthält, benennt sie ein Tool, dessen Schema die API in einer Anfrage abgelehnt hat. Claude Code sendet diese Anfrage erneut, wobei das Tool ohne Parameter deklariert wird.

• Wenn Ihre Sitzung mit einem 400-Fehler fehlschlägt, der ein Tool nach seiner Position benennt: Folgen Sie den Schritten unter Tool input schema is invalid
• Wenn Sie den Server verwenden: Sie müssen nichts tun. Claude kann das Tool weiterhin aufrufen, sieht aber seine Parameter nicht
• Wenn Sie den Server pflegen: Korrigieren Sie das Eingabeschema des Tools auf dem Server. Die Log-Zeile endet mit The API said: und dem Grund, aus dem die API das Schema abgelehnt hat. Validieren Sie die Argumente, die der Server empfängt, da Claude das Tool aufruft, ohne seine Parameter zu sehen

Vor v2.1.300 schlug jeder Turn, der das abgelehnte Schema enthielt, mit einem 400-Fehler fehl, der das Tool nach seiner Position benennt.

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 im Terminal 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.

Eine Elicitierungsanfrage in einer Cloud-Sitzung beantworten

Wenn Claudes Aufgabe in Ihrer Cloud-Sitzung auf die Anfrage eines MCP-Servers wartet, benötigt der Server etwas von Ihnen, etwa einen Wert oder eine Anmeldung. Wenn die Anfrage als Karte unter claude.ai/code oder auf dem Tab Code der Desktop-App erscheint, antworten Sie auf der Karte:

• Formularmodus: Füllen Sie die Felder aus und klicken Sie dann auf Submit
• URL-Modus: Klicken Sie auf Open link, schließen Sie den dadurch geöffneten Ablauf ab und klicken Sie dann auf der Karte auf I’m done, continue

Um die Anfrage abzulehnen, klicken Sie auf Decline. Claude fährt fort, sobald der Server antwortet.

Wenn Sie an keiner der beiden Stellen eine Karte sehen, können Sie die Anfrage dort nicht beantworten. Klicken Sie in Ihrer eigenen Sitzung dort auf die Stopp-Schaltfläche, um den Turn zu beenden.

Von Claude Code deklarierte Elicitierungsmodi

Wenn Sie einen MCP-Server erstellen, teilen die Client-Funktionen, die Claude Code beim Verbindungsaufbau sendet, Ihrem Server mit, welche Elicitierungsmodi er anfordern kann. Claude Code deklariert elicitation: {form: {}, url: {}} bei den folgenden Verbindungen, sodass ein Server auf jeder davon beide Modi anfordern kann:

• Verbindungen, die Protokollrevision 2026-07-28 verwenden
• Verbindungen mit den früheren Protokollrevisionen, 2025-11-25 und älter, zu den stdio-, sse-, http- und ws-Servern in der Claude Code-MCP-Konfiguration eines Benutzers. Erfordert Claude Code v2.1.287 oder höher

Bei seinen anderen Verbindungen mit den früheren Revisionen, etwa zu claude.ai-Konnektoren, deklariert Claude Code nur elicitation: {}, was Elicitierungsanfragen ausschließlich im Formularmodus erlaubt.

Ein Server, der auf dem Java MCP SDK 0.17.0 oder früher basiert, kann eine Deklaration ablehnen, die form und url enthält. Siehe MCP server rejected the elicitation capability.

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.

Die Längengrenzen für Beschreibungen ändern

Um die Standardgrenzen von 4.096 und 16.384 Zeichen für die MCP-Server in Ihrer Sitzung zu ändern, setzen Sie CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH auf eine Anzahl von Zeichen. Claude Code verwendet diese Zahl für beide Grenzen. Mit 8192 beispielsweise erhöhen Sie die Grenze von 4.096 Zeichen für Server-Anweisungen und vorab geladene Tool-Beschreibungen und senken die Grenze von 16.384 Zeichen für Tool-Beschreibungen, die über die Tool-Suche geladen werden. Diese Variable erfordert Claude Code v2.1.280 oder später.

Beschreibungen und Anweisungen einiger der MCP-Server, die Anthropic unter api.anthropic.com hostet, erreichen Claude vollständig, und das Setzen dieser Variablen kürzt sie nicht.

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.

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, erwartet Claude Code, dass das Gateway defer_loading-Tool-Felder und tool_reference-Blöcke zusammen mit dem anthropic-beta-Header weiterleitet. Die Tool-Suche ist hinter dem Gateway standardmäßig aktiviert, sodass MCP-Tools aufgeschoben werden und Anfragen diese Felder und Blöcke enthalten. 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. 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.

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.