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",
    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

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

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",
  "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",
                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",
    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",
    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 werfen UnsupportedMCPValueError, wenn ein MCP-Wert von der Claude API nicht unterstützt wird (in Go geben die Helfer einen UnsupportedValueError zurück; in Java und C# werfen sie AnthropicInvalidDataException). Dies kann bei nicht unterstützten Inhaltstypen, MIME-Typen oder Ressourcen-Links auftreten (löse Ressourcen-Links mit deinem MCP-Client auf, bevor du sie konvertierst).

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