MCP-Connector

Die Connector-Funktion für das „Model Context Protocol“, oder MCP, von Claude ermöglicht es dir, dich direkt aus der Messages API mit Remote-MCP-Servern zu verbinden, ohne einen separaten MCP-Client zu benötigen.

Hauptfunktionen

• Direkte API-Integration: Verbinde dich mit MCP-Servern, ohne einen MCP-Client zu implementieren
• Unterstützung für Tool-Aufrufe: Greife über die Messages API auf MCP-Tools zu
• Flexible Tool-Konfiguration: Aktiviere alle Tools, setze bestimmte Tools auf eine Allowlist oder unerwünschte Tools auf eine Denylist
• Konfiguration pro Tool: Konfiguriere einzelne Tools mit benutzerdefinierten Einstellungen
• OAuth-Authentifizierung: Unterstützung für OAuth-Bearer-Token für authentifizierte Server
• Mehrere Server: Verbinde dich in einer einzigen Anfrage mit mehreren MCP-Servern

Wann Claude MCP-Tools verwendet

Sobald ein MCP-Server verbunden ist, ruft Claude dessen Tools auf, wenn die Anfrage des Nutzers der beschriebenen Fähigkeit eines Tools entspricht – entweder explizit („durchsuche Jira nach offenen Bugs“) oder implizit („was blockiert das Release?“ mit einem angebundenen Jira-Server).

Claude ruft kein MCP-Tool für allgemeine Wissensfragen zu einem verbundenen Dienst auf. Die Frage „wie funktionieren Notion-Datenbanken?“ mit einem angebundenen Notion-Server wird direkt beantwortet; die Frage „was befindet sich in meiner Projects-Datenbank?“ löst das Tool aus.

Du kannst über deinen System-Prompt steuern, wie bereitwillig Claude MCP-Tools aufruft. Siehe Wann Claude Tools verwendet für allgemeine Hinweise und Beispielformulierungen.

Einschränkungen

• Vom Funktionsumfang der MCP-Spezifikation werden derzeit nur Tool-Aufrufe unterstützt.
• Der Server muss öffentlich über HTTP erreichbar sein (unterstützt werden sowohl Streamable-HTTP- als auch SSE-Transporte). Lokale STDIO-Server können nicht direkt verbunden werden.

Verwendung des MCP-Connectors in der Messages API

Der MCP-Connector verwendet zwei Komponenten:

1. MCP-Server-Definition (mcp_servers-Array): Definiert die Verbindungsdetails des Servers (URL, Authentifizierung)
2. MCP-Toolset (tools-Array): Konfiguriert, welche Tools aktiviert werden und wie sie konfiguriert werden

Einfaches Beispiel

Dieses Beispiel aktiviert alle Tools eines MCP-Servers mit der Standardkonfiguration:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have available?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://example-server.modelcontextprotocol.io/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

print(response)

MCP-Server-Konfiguration

Jeder MCP-Server im mcp_servers-Array definiert die Verbindungsdetails:

{
  "type": "url",
  "url": "https://example-server.modelcontextprotocol.io/sse",
  "name": "example-mcp",
  "authorization_token": "YOUR_TOKEN"
}

Feldbeschreibungen

MCP-Toolset-Konfiguration

Das MCPToolset befindet sich im tools-Array und konfiguriert, welche Tools des MCP-Servers aktiviert sind und wie sie konfiguriert werden sollen.

Grundstruktur

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "default_config": {
    "enabled": true,
    "defer_loading": false
  },
  "configs": {
    "specific_tool_name": {
      "enabled": true,
      "defer_loading": true
    }
  }
}

Feldbeschreibungen

Mit dem Beta-Header mcp-client-2026-09-15 akzeptiert ein MCPToolset außerdem tools, eine fixierte Kopie der Tool-Liste des Servers. Siehe Die Tool-Liste eines MCP-Servers fixieren.

Tool-Konfigurationsoptionen

Jedes Tool (ob in default_config oder in configs konfiguriert) unterstützt die folgenden Felder:

Das vollständige Verzeichnis der von Anthropic bereitgestellten Tools und optionaler Eigenschaften wie defer_loading findest du in der Tool-Referenz. Um große Tool-Sets zu durchsuchen, siehe Tool-Search-Tool.

Zusammenführung der Konfiguration

Konfigurationswerte werden mit folgender Priorität zusammengeführt (höchste bis niedrigste):

1. Tool-spezifische Einstellungen in configs
2. default_config auf Set-Ebene
3. Systemstandardwerte

Beispiel:

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

Ergibt:

• search_events: enabled: false (aus configs), defer_loading: true (aus default_config)
• Alle anderen Tools: enabled: true (Systemstandard), defer_loading: true (aus default_config)

Gängige Konfigurationsmuster

Alle Tools mit Standardkonfiguration aktivieren

Das einfachste Muster: alle Tools eines Servers aktivieren:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp"
}

Allowlist: nur bestimmte Tools aktivieren

Setze enabled: false als Standard und aktiviere dann explizit bestimmte Tools:

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

Denylist: bestimmte Tools deaktivieren

Aktiviere standardmäßig alle Tools und deaktiviere dann explizit unerwünschte Tools. Das Setzen von schreibenden oder destruktiven Tools auf eine Denylist wird empfohlen, wenn du reine Lese-Assistenten erstellst oder wenn du vor Zustandsänderungen einen menschlichen Bestätigungsschritt wünschst:

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

Gemischt: Allowlist mit Konfiguration pro Tool

Kombiniere eine Allowlist mit benutzerdefinierter Konfiguration für jedes Tool:

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

In diesem Beispiel:

• search_events ist mit defer_loading: false aktiviert
• list_events ist mit defer_loading: true aktiviert (von default_config geerbt)
• Alle anderen Tools sind deaktiviert

Validierungsregeln

Die API erzwingt diese Validierungsregeln:

• Server muss existieren: Der mcp_server_name in einem MCPToolset muss mit einem im mcp_servers-Array definierten Server übereinstimmen
• Server muss verwendet werden: Jeder in mcp_servers definierte MCP-Server muss von genau einem MCPToolset referenziert werden
• Eindeutiges Toolset pro Server: Jeder MCP-Server kann nur von einem MCPToolset referenziert werden
• Unbekannte Tool-Namen: Wenn ein Tool-Name in configs auf dem MCP-Server nicht existiert, wird eine Backend-Warnung protokolliert, aber kein Fehler zurückgegeben (MCP-Server können eine dynamische Tool-Verfügbarkeit haben)

Antwort-Inhaltstypen

Wenn Claude MCP-Tools verwendet, enthält die Antwort zwei neue Content-Block-Typen:

MCP-Tool-Use-Block

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCP-Tool-Result-Block

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

Die Tool-Liste eines MCP-Servers fixieren (Beta)

Ein MCP-Server kann seine Tools jederzeit ändern. Der Beta-Header mcp-client-2026-09-15 zeichnet die Tool-Liste auf, die jeder Server zurückgibt, und ermöglicht es dir, sie zu fixieren, sodass ein Server, der seine Tools ändert, nicht mitten in einer Konversation verändert, was Claude sieht. Er umfasst alles, was mcp-client-2025-11-20 bietet, also sende ihn anstelle dieses Headers. Er ist auf der Claude API verfügbar.

Wenn die API einen MCP-Server beim Erzeugen einer Antwort nach seinen Tools fragt, beginnt die Antwort mit einem mcp_tool_listing-Block für diesen Server, je ein Block pro abgefragtem Server:

{
  "type": "mcp_tool_listing",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Wenn dein Code content[0] liest, überspringe diese Blöcke. Sende die Assistant-Nachricht unverändert zurück, einschließlich der mcp_tool_listing-Blöcke, und sende mcp-client-2026-09-15 weiterhin bei jeder Anfrage mit, die einen solchen Block enthält. Spätere Anfragen verwenden dann die aufgezeichnete Liste für diesen Server, anstatt ihn erneut abzufragen.

Um eine Liste selbst zu fixieren, kopiere die tools eines Blocks in das tools-Feld des MCPToolsets dieses Servers. Die API fragt den Server dann nicht nach seinen Tools, und die Tools des Toolsets sind genau diese Einträge, wobei default_config und configs angewendet werden:

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "tools": [
    {
      "name": "echo",
      "description": "Returns the text it receives.",
      "input_schema": {
        "type": "object",
        "properties": { "text": { "type": "string" } },
        "required": ["text"]
      }
    }
  ]
}

Jeder Eintrag in tools enthält den name des Tools, wie der Server ihn auflistet (ohne den Servernamen), seine description und sein input_schema.

Das folgende Beispiel sendet eine Anfrage mit einem nicht fixierten Toolset, kopiert die zurückgegebene Liste in das tools-Feld des Toolsets und sendet die Anfrage erneut. Die zweite Antwort enthält keinen mcp_tool_listing-Block, da die API den Server nicht abfragt:

from anthropic.types.beta import (
    BetaMessageParam,
    BetaRequestMCPServerURLDefinitionParam,
)

client = anthropic.Anthropic()

mcp_servers: list[BetaRequestMCPServerURLDefinitionParam] = [
    {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN",
    },
]
messages: list[BetaMessageParam] = [
    {"role": "user", "content": "What tools do you have available?"},
]

# Erste Anfrage: Das Toolset ist nicht fixiert, daher fragt die API den Server nach
# seinen Tools, und die Antwort beginnt mit einem mcp_tool_listing-Block.
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    messages=messages,
)

listing = next(block for block in first.content if block.type == "mcp_tool_listing")
print([tool.name for tool in listing.tools])

# Fixiere die Liste: Kopiere die Tools des Blocks in das Toolset. Die API verwendet
# genau diese Einträge und fragt den Server nicht erneut.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    betas=["mcp-client-2026-09-15"],
    mcp_servers=mcp_servers,
    tools=[
        {
            "type": "mcp_toolset",
            "mcp_server_name": "example-mcp",
            "tools": [
                {
                    "name": tool.name,
                    "description": tool.description,
                    "input_schema": tool.input_schema,
                }
                for tool in listing.tools
            ],
        },
    ],
    messages=messages,
)

# Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
print([block.type for block in second.content])

Wenn du zusätzlich den Beta-Header inline-tools-2026-09-15 verwendest, kannst du mitten in einer Konversation einen MCP-Server hinzufügen. Siehe Einen MCP-Server mitten im Gespräch hinzufügen.

Mehrere MCP-Server

Du kannst dich mit mehreren MCP-Servern verbinden, indem du mehrere Server-Definitionen in mcp_servers und für jeden ein entsprechendes MCPToolset im tools-Array angibst:

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [
    {
      "role": "user",
      "content": "Use tools from both mcp-server-1 and mcp-server-2 to complete this task"
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example1.com/sse",
      "name": "mcp-server-1",
      "authorization_token": "TOKEN1"
    },
    {
      "type": "url",
      "url": "https://mcp.example2.com/sse",
      "name": "mcp-server-2",
      "authorization_token": "TOKEN2"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-1"
    },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "mcp-server-2",
      "default_config": {
        "defer_loading": true
      }
    }
  ]
}

Wenn viele Tools verfügbar sind, wählt Claude anhand von Tool-Namen und -Beschreibungen aus. Klare, spezifische Tool-Beschreibungen verbessern die Auswahlgenauigkeit. Bei großen Tool-Sets (Dutzende von Tools über mehrere Server hinweg) solltest du in Erwägung ziehen, defer_loading zusammen mit dem Tool-Search-Tool zu aktivieren, damit pro Anfrage nur relevante Tools angezeigt werden.

Authentifizierung

Für MCP-Server, die eine OAuth-Authentifizierung erfordern, musst du ein Access-Token beschaffen. Die MCP-Connector-Beta unterstützt die Übergabe eines authorization_token-Parameters in der MCP-Server-Definition. Von API-Nutzern wird erwartet, dass sie den OAuth-Flow abwickeln und das Access-Token vor dem API-Aufruf beschaffen sowie das Token bei Bedarf erneuern.

Ein Access-Token zum Testen beschaffen

Der MCP-Inspector kann dich durch den Prozess führen, ein Access-Token zu Testzwecken zu beschaffen.

1. Führe den Inspector mit dem folgenden Befehl aus. Du benötigst Node.js auf deinem Rechner.

   npx @modelcontextprotocol/inspector

   

2. Wähle in der Seitenleiste links für Transport type entweder SSE oder Streamable HTTP aus.

3. Gib die URL des MCP-Servers ein.

4. Klicke im rechten Bereich auf Open Auth Settings nach Need to configure authentication?.

5. Klicke auf Quick OAuth Flow und autorisiere auf dem OAuth-Bildschirm.

6. Folge den Schritten im Abschnitt OAuth Flow Progress des Inspectors und klicke auf Continue, bis du Authentication complete erreichst.

7. Kopiere den Wert von access_token.

8. Füge ihn in das Feld authorization_token deiner MCP-Server-Konfiguration ein.

Das Access-Token verwenden

Sobald du über einen der vorangehenden OAuth-Flows ein Access-Token erhalten hast, kannst du es in deiner MCP-Server-Konfiguration verwenden:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "authenticated-server",
      "authorization_token": "YOUR_ACCESS_TOKEN_HERE"
    }
  ]
}

Ausführliche Erläuterungen zum OAuth-Flow findest du im Abschnitt Authorization der MCP-Spezifikation.

Clientseitige MCP-Helfer

Wenn du deine eigene MCP-Client-Verbindung verwaltest (zum Beispiel mit lokalen stdio-Servern, MCP-Prompts oder MCP-Ressourcen), stellen die SDKs Hilfsfunktionen bereit, die zwischen MCP-Typen und Claude-API-Typen konvertieren. Dadurch entfällt manueller Konvertierungscode, wenn du ein MCP-SDK für deine Sprache (zum Beispiel das TypeScript MCP SDK) zusammen mit dem Anthropic SDK verwendest.

Installation

Installiere sowohl das Anthropic SDK als auch das MCP SDK:

pip install "anthropic[mcp]"

Verfügbare Helfer

Importiere die Helfer für deine Sprache:

from anthropic.lib.tools.mcp import (
    async_mcp_tool,
    mcp_message,
    mcp_resource_to_content,
    mcp_resource_to_file,
)

Die Namen und genauen Signaturen der Helfer folgen den Konventionen der jeweiligen Sprache; diese Tabelle zeigt die TypeScript-Formen:

MCP-Tools verwenden

Konvertiere MCP-Tools zur Verwendung mit dem Tool-Runner des SDK, der die Tool-Ausführung automatisch übernimmt:

from anthropic.lib.tools.mcp import async_mcp_tool
from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

client = AsyncAnthropic()


async def main() -> None:
    # Mit einem MCP-Server verbinden
    server_params = StdioServerParameters(command="mcp-server")
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as mcp_client:
            await mcp_client.initialize()

            # Tools auflisten und für die Claude API konvertieren
            tools_result = await mcp_client.list_tools()
            runner = client.beta.messages.tool_runner(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {"role": "user", "content": "What tools do you have available?"},
                ],
                tools=[async_mcp_tool(tool, mcp_client) for tool in tools_result.tools],
            )

            final_message = await runner.until_done()
            print(final_message)


asyncio.run(main())

MCP-Prompts verwenden

Konvertiere MCP-Prompt-Nachrichten in das Claude-API-Nachrichtenformat:

from anthropic.lib.tools.mcp import mcp_message

prompt = await mcp_client.get_prompt(name="my-prompt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[mcp_message(message) for message in prompt.messages],
)

print(response)

MCP-Ressourcen verwenden

Konvertiere MCP-Ressourcen in Content-Blöcke, um sie in Nachrichten einzubinden, oder in Dateiobjekte zum Hochladen:

from anthropic.lib.tools.mcp import (
    mcp_resource_to_content,
    mcp_resource_to_file,
)

# Als Inhaltsblock in einer Nachricht
resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt")
response = await client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                mcp_resource_to_content(resource),
                {"type": "text", "text": "Summarize this document"},
            ],
        }
    ],
)
print(response)

# Als Datei-Upload
file_resource = await mcp_client.read_resource(
    uri="file:///path/to/data.json",
)
uploaded = await client.files.upload(
    file=mcp_resource_to_file(file_resource),
)
print(uploaded.id)

Fehlerbehandlung

Die Konvertierungsfunktionen schlagen mit UnsupportedMCPValueError fehl, wenn ein MCP-Wert von der Claude API nicht unterstützt wird (als Ausnahme ausgelöst bzw. in Go als Fehler zurückgegeben). Dies kann bei nicht unterstützten Inhaltstypen, MIME-Typen oder Ressourcenlinks auftreten (löse Ressourcenlinks vor der Konvertierung mit deinem MCP-Client auf).

Batch-Anfragen

Du kannst mcp_servers in Anfragen an die Message Batches API einbinden. MCP-Tool-Aufrufe über die Batches API werden genauso abgerechnet wie in regulären Messages-API-Anfragen.

Datenaufbewahrung

Der MCP-Connector ist nicht durch ZDR-Vereinbarungen abgedeckt. Mit MCP-Servern ausgetauschte Daten, einschließlich Tool-Definitionen und Ausführungsergebnissen, werden gemäß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Zur ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenaufbewahrung.

Migrationsleitfaden

Wenn du den abgekündigten Beta-Header mcp-client-2025-04-04 verwendest, folge diesem Leitfaden, um auf die neue Version zu migrieren.

Wichtige Änderungen

1. Neuer Beta-Header: Wechsle von mcp-client-2025-04-04 zu mcp-client-2025-11-20
2. Tool-Konfiguration verschoben: Die Tool-Konfiguration befindet sich jetzt als MCPToolset-Objekte im tools-Array, nicht mehr in der MCP-Server-Definition
3. Flexiblere Konfiguration: Das neue Muster unterstützt Allowlists, Denylists und Konfiguration pro Tool

Migrationsschritte

Vorher (abgekündigt):

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["tool1", "tool2"]
      }
    }
  ]
}

Nachher (aktuell):

{
  "model": "claude-opus-5-5",
  "max_tokens": 1000,
  "messages": [
    // ...
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.example.com/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN"
    }
  ],
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "example-mcp",
      "default_config": {
        "enabled": false
      },
      "configs": {
        "tool1": {
          "enabled": true
        },
        "tool2": {
          "enabled": true
        }
      }
    }
  ]
}

Gängige Migrationsmuster

Abgekündigte Version: mcp-client-2025-04-04

Die vorherige Version des MCP-Connectors enthielt die Tool-Konfiguration direkt in der MCP-Server-Definition:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Abgekündigte Feldbeschreibungen

Compatibility