MCP-Connector

Claudes „Model Context Protocol" (MCP)-Connector-Feature ermöglicht es dir, dich direkt über die 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, erstelle eine Allowlist für bestimmte Tools oder eine Denylist für unerwünschte Tools
• 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 zu einer beschriebenen Fähigkeit eines Tools passt – 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 über einen verbundenen Dienst auf. Die Frage „Wie funktionieren Notion-Datenbanken?" mit einem angebundenen Notion-Server wird direkt beantwortet; die Frage „Was steht 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 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 sollen



Einfaches Beispiel

Dieses Beispiel aktiviert alle Tools eines MCP-Servers mit 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 optionalen Eigenschaften wie defer_loading findest du in der Tool-Referenz. Für die Suche in großen Tool-Sets siehe Tool-Search-Tool.



Zusammenführung der Konfiguration

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

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

Beispiel:

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

Ergebnis:

• 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 – aktiviere alle Tools eines Servers:

{
  "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 Ausschließen von schreibenden oder destruktiven Tools per Denylist wird empfohlen, wenn du schreibgeschützte Assistenten baust oder wenn du vor Zustandsänderungen einen menschlichen Bestätigungsschritt möchtest:

{
  "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 Allowlisting 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 aktiviert mit defer_loading: false
• list_events ist aktiviert mit defer_loading: true (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 Server übereinstimmen, der im mcp_servers-Array definiert ist
• 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)



Response-Content-Typen

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 ein entsprechendes MCPToolset für jeden 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 basierend auf 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 erwägen, defer_loading 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 die Schaltfläche „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 access_token-Wert.

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



Das Access-Token verwenden

Sobald du ein Access-Token über einen der vorangegangenen OAuth-Flows 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 Erklärungen zum OAuth-Flow findest du im Abschnitt Authorization der MCP-Spezifikation.



Clientseitige MCP-Helper

Wenn du deine eigene MCP-Client-Verbindung verwaltest (zum Beispiel mit lokalen stdio-Servern, MCP-Prompts oder MCP-Ressourcen), stellen die SDKs Helper-Funktionen bereit, die zwischen MCP-Typen und Claude-API-Typen konvertieren. Dies erspart manuellen 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 Helper

Importiere die Helper für deine Sprache:

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

Helper-Namen und genaue Signaturen 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 zur Einbindung in Nachrichten oder in Dateiobjekte zum Hochladen:

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

# As a content block in a message
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)

# As a file 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 Helper einen UnsupportedValueError zurück; in Java und C# werfen sie AnthropicInvalidDataException). Dies kann bei nicht unterstützten Content-Typen, MIME-Typen oder Ressourcen-Links passieren (löse Ressourcen-Links mit deinem MCP-Client auf, bevor du konvertierst).



Batch-Anfragen

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



Datenaufbewahrung

Der MCP-Connector ist nicht durch ZDR-Vereinbarungen abgedeckt. Daten, die mit MCP-Servern ausgetauscht werden, einschließlich Tool-Definitionen und Ausführungsergebnissen, werden gemäß Anthropics Standard-Datenaufbewahrungsrichtlinie aufbewahrt.

Zur ZDR-Eignung aller Features siehe API und Datenaufbewahrung.



Migrationsleitfaden

Wenn du den veralteten 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 im tools-Array als MCPToolset-Objekte, nicht in der MCP-Server-Definition
3. Flexiblere Konfiguration: Das neue Muster unterstützt Allowlisting, Denylisting und Konfiguration pro Tool



Migrationsschritte

Vorher (veraltet):

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



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



Veraltete Feldbeschreibungen