MCP & Verbindung zu Tools

Experte

Das Model Context Protocol (MCP) ist der offene Standard, um KI mit externen Tools und Daten zu verbinden. In der API musst du gar keinen MCP-Client selbst betreiben: Der MCP-Connector lässt dich in deinem Request einen Remote-Server nennen, und Claude ruft dessen Tools innerhalb des normalen Agent-Loops auf. Zwei Request-Felder ersetzen eine ganze Integrationsschicht.

What you'll learn

Wann der MCP-Connector hand-definierte Tools schlägt — und wann nicht
Die exakte Request-Form: mcp_servers für die Verbindung, mcp_toolset für die Policy
Allowlist, Denylist und Per-Tool-Config — und wie sich die drei Config-Schichten mischen
Die Response-Blöcke, die du behandeln musst: mcp_tool_use und mcp_tool_result
Die echten Grenzen: nur HTTPS, nur Tools, Plattformlücken und keine ZDR-Abdeckung

MCP vs. hand-definierte Tools

	Tool Use (custom)	MCP-Connector
Du definierst	Das Schema jedes Tools, und du führst es aus	Eine Verbindung zu einem Server, der Tools publiziert
Wer führt das Tool aus	Dein Code, in deinem Loop	Anthropics Seite ruft den Remote-Server auf
Am besten für	Ein paar bespoke Funktionen in deiner App	Wiederverwendung bestehender Integrationen (GitHub, DBs, Browser, SaaS)
Auth	Dein Code	Ein OAuth-Bearer-Token, das du pro Server lieferst

Sie koexistieren. Definiere deine app-spezifischen Tools direkt und zieh vorgefertigte Fähigkeit über MCP dazu.

Die Request-Form

Zwei Teile, und sie sind bewusst getrennt: mcp_servers sagt, wo der Server ist und wie authentifiziert wird; der mcp_toolset-Eintrag im tools-Array sagt, welche seiner Tools du bereit bist freizugeben und wie.

Guided walkthrough1 of 4

anthropic-beta: mcp-client-2025-11-20 — ohne ihn wird das mcp_servers-Feld nicht akzeptiert. In den SDKs ist das die betas-Liste in einem beta.messages.create-Call.

Minimaler MCP-Connector-Call (cURL)

curl https://api.anthropic.com/v1/messages \
-H "Content-Type: application/json" \
-H "X-API-Key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: mcp-client-2025-11-20" \
-d '{
  "model": "MODEL_ID",
  "max_tokens": 1000,
  "messages": [{"role": "user", "content": "What tools do you have available?"}],
  "mcp_servers": [
    {"type": "url", "url": "https://example.com/sse", "name": "example-mcp", "authorization_token": "YOUR_TOKEN"}
  ],
  "tools": [
    {"type": "mcp_toolset", "mcp_server_name": "example-mcp"}
  ]
}'

:::tip Modell niemals hart codieren MODEL_ID oben ist bewusst ein Platzhalter. Lies die aktuelle ID aus Aktuelle Modelle & Preise und halte sie in der Config, damit ein Modell-Upgrade eine Ein-Zeilen-Änderung ist. :::

Die API erzwingt strikte Paarung: Jeder Server in mcp_servers muss von genau einem Toolset referenziert werden, und jedes Toolset-mcp_server_name muss zu einem deklarierten Server passen. Mismatches sind Validierungsfehler, keine stillen No-Ops.

Wähle, was Claude tatsächlich darf

Diesen Teil bekommen die meisten Integrationen falsch hin. Ein Toolset nimmt ein default_config, das auf jedes Tool angewandt wird, plus configs mit Per-Tool-Overrides. Priorität, höchste zuerst: Per-Tool configs → set-weites default_config → System-Defaults.

Denylist — alles aktivieren, dann die gefährlichen abschalten. Sinnvoll, wenn du Breite willst, aber keine zerstörerischen Writes:

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "configs": {
    "delete_all_events": { "enabled": false },
    "share_calendar_publicly": { "enabled": false }
  }
}

Allowlist — per Default deaktivieren, dann die Überlebenden namentlich nennen. Das ist die Least-Privilege-Haltung — und die, zu der man per Default greift:

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "default_config": { "enabled": false },
  "configs": {
    "search_events": { "enabled": true },
    "create_event": { "enabled": true }
  }
}

:::warning Eine Denylist blockiert nur das, an das du gedacht hast Server können Tools ergänzen. Eine Denylist gewährt still jedes Tool, das nach ihrem Schreiben ausgeliefert wurde; eine Allowlist ignoriert sie still. Für alles, was Kundendaten oder Geld berührt, allowliste. Beachte auch: Ein Tool in configs zu nennen, das es auf dem Server nicht gibt, loggt eine Backend-Warnung, wirft aber keinen Fehler — ein Tippfehler in einer Allowlist deaktiviert also still das Tool, das du eigentlich freischalten wolltest. Verifiziere gegen die Live-Toolliste des Servers. :::

Halte die Schemata aus deinem Kontext raus

Die Beschreibung jedes aktivierten Tools wird mit dem Request geschickt, ein fetter Katalog belastet also jeden Turn. Die Antwort des Connectors ist defer_loading: true: Die Beschreibung bleibt aus dem initialen Kontext und Claude zieht sie bei Bedarf via Tool Search Tool nach.

{
  "type": "mcp_toolset",
  "mcp_server_name": "calendar-mcp",
  "default_config": { "defer_loading": true },
  "configs": {
    "search_events": { "defer_loading": false }
  }
}

Lies das so: alles deferren außer dem einen Tool, mit dem diese Aufgabe startet. Ein Toolset akzeptiert auch cache_control, sodass ein stabiler Katalog hinter einem Prompt-Caching-Breakpoint sitzen kann, statt jeden Turn neu abgerechnet zu werden. Für die Zahlen dahinter — und warum das Deferren von Tools die Selection-Accuracy erhöht statt sie zu senken — siehe Die MCP-Token-Steuer. Wenn nicht die Definitionen, sondern die Ergebnisse deinen Kontext fluten, greife stattdessen zu Programmatic Tool Calling.

Was zurückkommt

Zwei Content-Block-Typen, die du behandeln musst:

{ "type": "mcp_tool_use", "id": "mcptoolu_...", "name": "echo",
  "server_name": "example-mcp", "input": { "param1": "value1" } }

{ "type": "mcp_tool_result", "tool_use_id": "mcptoolu_...", "is_error": false,
  "content": [ { "type": "text", "text": "Hello" } ] }

Beachte server_name am Use-Block: Mit mehreren angebundenen Servern ist das der Weg, einen Call zuzuordnen — essenziell für Logging und um zu debuggen, welche Integration schiefging. Und is_error ist ein Feld, keine Exception: Ein fehlgeschlagenes MCP-Tool kommt als Result zurück, dein Loop muss es also prüfen, statt Erfolg anzunehmen.

Die Grenzen, die beißen

Watch out

Nur Tools. Von der MCP-Spec unterstützt der Connector derzeit Tool-Calls — nicht Prompts oder Resources. Brauchst du die? Betreibe einen eigenen Client und nutze die SDK-MCP-Helper.
Nur remote HTTPS. Der Server muss öffentlich über HTTP erreichbar sein (Streamable HTTP oder SSE Transports). Ein lokaler stdio-Server kann so nicht angebunden werden — das ist, was Claude Code und die Desktop-Apps tun.
Plattformlücken. Verfügbar auf der Claude API, Claude Platform on AWS und Microsoft Foundry (Hosted-on-Anthropic-Deployments). Derzeit nicht auf Amazon Bedrock oder Google Cloud.
Kein Zero-Data-Retention. Mit MCP-Servern ausgetauschte Daten — Tool-Definitionen und Ausführungsergebnisse — fallen unter die Standard-Retention, nicht unter ZDR.
Du besitzt das OAuth. Die API nimmt ein authorization_token; es zu beschaffen und vor Ablauf zu refreshen ist deine Aufgabe.

Derselbe Standard, drei Oberflächen

API (diese Seite) — Remote-Server per URL, via Connector.
Claude Code — lokale und remote Server in deinen Dev-Sessions.
Die Apps — MCP treibt Connectors.

Lerne das Protokoll einmal; es überträgt sich. Nur die Verdrahtung unterscheidet sich.

Vertrauen

:::warning Ein MCP-Server ist Code plus Zugriff Binde nur Server an, denen du vertraust, halte sie mit einer Allowlist auf Least Privilege und denk daran: Inhalte, die ein Server zurückgibt, sind untrusted Input und können Prompt Injection tragen. Prüfe Drittanbieter-Server, bevor du sie verdrahtest — Drittanbieter-Code prüfen und MCP-Server absichern. :::

MCP-Connector-Vokabular

Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.

1 / 6

Prüfe dich selbst

0/4

Du willst, dass Claude nur search_events und create_event von einem Kalender-Server nutzt. Wie sieht das korrekte Toolset aus?
Ein MCP-Tool-Call scheitert. Wo taucht das auf?
Du brauchst, dass Claude MCP-Resources von einem lokalen stdio-Server liest. Kann der Connector das?
Dein Tool-Katalog spannt vier Server und dominiert jeden Turn das Kontextfenster. Günstigster erster Zug?

Key takeaways

Der Connector ersetzt einen MCP-Client mit zwei Request-Feldern — aber nur für Remote-HTTPS-Server und nur für Tool-Calls.
mcp_servers ist die Verbindung; das mcp_toolset in tools ist die Policy. Jeder Server muss mit genau einem Toolset paaren.
Allowlist (default_config.enabled false plus explizite configs) schlägt Denylist: Später zum Server hinzugefügte Tools werden ignoriert, nicht gewährt.
defer_loading und cache_control sind deine Hebel, wenn Tool-Schemata das Kontextfenster zu fressen beginnen.
mcp_tool_use- und mcp_tool_result-Blöcke behandeln — inklusive is_error, das ein Feld ist, keine Exception.
Prüfe den Beta-Header vor dem Ausliefern: mcp-client-2025-11-20 ist aktuell, mcp-client-2025-04-04 ist deprecated.

Quellen & weiterführend

MCP-Connector — Anthropic-Doku — die maßgebliche Feldreferenz und Migrations-Guide.
Model Context Protocol Specification — der offene Standard selbst, inklusive Authorization.

MCP vs. hand-definierte Tools​

Die Request-Form​

Minimaler MCP-Connector-Call (cURL)

Wähle, was Claude tatsächlich darf​

Halte die Schemata aus deinem Kontext raus​

Was zurückkommt​

Die Grenzen, die beißen​

Derselbe Standard, drei Oberflächen​

Vertrauen​