---
title: MCP-Connector
url: https://platform.claude.com/docs/de/agents-and-tools/mcp-connector
description: Verbinde dich direkt aus der Messages API mit Remote-MCP-Servern, ohne einen MCP-Client zu benötigen, und setze einzelne Tools auf eine Allowlist oder Denylist oder konfiguriere sie individuell.
featureMetadata:
status: beta
betaHeader: mcp-client-2025-11-20
zdr: not-eligible
supportedPlatforms:
Claude API: beta
Claude Platform on AWS: beta
Microsoft Foundry: beta
---
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.
Die vorherige Version dieser Funktion (`mcp-client-2025-04-04`) ist abgekündigt. Siehe [Abgekündigte Version: mcp-client-2025-04-04](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).
## 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](https://platform.claude.com/docs/de/agents-and-tools/tool-use/overview#when-claude-uses-tools) für allgemeine Hinweise und Beispielformulierungen.
## Einschränkungen
* Vom Funktionsumfang der [MCP-Spezifikation](https://modelcontextprotocol.io/introduction#explore-mcp) werden derzeit nur [Tool-Aufrufe](https://modelcontextprotocol.io/docs/concepts/tools) 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:
```bash 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": "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"
}
]
}'
```
```bash CLI
ant beta:messages create --beta mcp-client-2025-11-20 <<'YAML'
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
YAML
```
```python Python
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)
```
```typescript TypeScript
const anthropic = new Anthropic();
const response = await anthropic.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"]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1000,
Messages = new List
{
new() { Role = Role.User, Content = "What tools do you have available?" }
},
McpServers = new List
{
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN"
}
},
Tools = new List
{
new BetaMcpToolset("example-mcp")
},
Betas = [AnthropicBeta.McpClient2025_11_20]
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
MCPServers: []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
},
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
}},
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaMCPClient2025_11_20,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaMcpToolset;
// ...
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1000L)
.addUserMessage("What tools do you have available?")
.addMcpServer(BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build())
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addBeta(AnthropicBeta.MCP_CLIENT_2025_11_20)
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->beta->messages->create(
maxTokens: 1000,
messages: [
['role' => 'user', 'content' => 'What tools do you have available?']
],
model: 'claude-opus-5-5',
mcpServers: [
[
'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'],
);
echo $message;
```
```ruby Ruby
client = Anthropic::Client.new
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"]
)
puts response
```
## MCP-Server-Konfiguration
Jeder MCP-Server im `mcp_servers`-Array definiert die Verbindungsdetails:
```json
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}
```
### Feldbeschreibungen
| Eigenschaft | Typ | Erforderlich | Beschreibung |
| --------------------- | ------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | Ja | Derzeit wird nur "url" unterstützt. |
| `url` | string | Ja | Die URL des MCP-Servers. Muss mit https\:// beginnen. |
| `name` | string | Ja | Ein eindeutiger Bezeichner für diesen MCP-Server. Muss von genau einem MCPToolset im `tools`-Array referenziert werden. |
| `authorization_token` | string | Nein | OAuth-Autorisierungstoken, falls vom MCP-Server benötigt. Siehe [Authentifizierung](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#authentication), um zu erfahren, wie du eines erhältst, oder die [MCP-Spezifikation](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) für Protokolldetails. |
## 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
```json
{
"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
| Eigenschaft | Typ | Erforderlich | Beschreibung |
| ----------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | Ja | Muss "mcp\_toolset" sein. |
| `mcp_server_name` | string | Ja | Muss mit einem im `mcp_servers`-Array definierten Servernamen übereinstimmen. |
| `default_config` | object | Nein | Standardkonfiguration, die auf alle Tools in diesem Set angewendet wird. Einzelne Tool-Konfigurationen in `configs` überschreiben diese Standardwerte. |
| `configs` | object | Nein | Überschreibungen der Konfiguration pro Tool. Schlüssel sind Tool-Namen, Werte sind Konfigurationsobjekte. |
| `cache_control` | object | Nein | Konfiguration des Cache-Breakpoints für [Prompt-Caching](https://platform.claude.com/docs/de/build-with-claude/prompt-caching) für dieses Toolset. |
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](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#pin-mcp-tool-list).
### Tool-Konfigurationsoptionen
Jedes Tool (ob in `default_config` oder in `configs` konfiguriert) unterstützt die folgenden Felder:
| Eigenschaft | Typ | Standard | Beschreibung |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | Ob dieses Tool aktiviert ist. |
| `defer_loading` | boolean | `false` | Wenn true, wird die Tool-Beschreibung zunächst nicht an das Modell gesendet. Wird mit dem [Tool-Search-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-search-tool) verwendet. |
Das vollständige Verzeichnis der von Anthropic bereitgestellten Tools und optionaler Eigenschaften wie `defer_loading` findest du in der [Tool-Referenz](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-reference). Um große Tool-Sets zu durchsuchen, siehe [Tool-Search-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```json
{
"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
```json
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}
```
### MCP-Tool-Result-Block
```json
{
"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:
```json
{
"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:
```json
{
"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:
```bash cURL
BODY='{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"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"
}
],
"messages": [
{
"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.
# tee zeigt die Antwort auf stderr an, während die Variable sie erfasst.
FIRST=$(curl -sS 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-2026-09-15" \
-d "$BODY" | tee /dev/stderr)
# Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Die API verwendet
# genau diese Einträge und fragt den Server nicht erneut.
TOOLS=$(jq '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$FIRST")
PINNED=$(jq --argjson tools "$TOOLS" '.tools[0].tools = $tools' <<<"$BODY")
# Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
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-2026-09-15" \
-d "$PINNED"
```
```bash CLI
request=$(cat <<'YAML'
model: claude-opus-5-5
max_tokens: 1024
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
messages:
- role: user
content: What tools do you have available?
YAML
)
# 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.
# tee zeigt die Antwort auf stderr an, während die Variable sie erfasst.
first=$(ant beta:messages create --beta mcp-client-2026-09-15 --format json \
<<<"$request" | tee /dev/stderr)
tools=$(jq -c '.content[] | select(.type == "mcp_tool_listing") | .tools' \
<<<"$first")
# Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Das Flag --tool
# ersetzt das tools-Array im Body. Die API verwendet genau diese Einträge und
# fragt den Server nicht erneut, daher enthält die Antwort keinen mcp_tool_listing-Block.
ant beta:messages create --beta mcp-client-2026-09-15 \
--tool "{type: mcp_toolset, mcp_server_name: example-mcp, tools: $tools}" \
<<<"$request"
```
```python Python
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])
```
```typescript TypeScript
const client = new Anthropic();
const mcpServers: Anthropic.Beta.BetaRequestMCPServerURLDefinition[] = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
];
const messages: Anthropic.Beta.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.
const first = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages
});
const listing = first.content.find((block) => block.type === "mcp_tool_listing");
if (!listing) {
throw new Error("The response has no mcp_tool_listing block.");
}
console.log(listing.tools.map((tool) => tool.name));
// Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Die API verwendet
// genau diese Einträge und fragt den Server nicht erneut.
const second = await client.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
betas: ["mcp-client-2026-09-15"],
mcp_servers: mcpServers,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools
}
],
messages
});
// Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
console.log(second.content.map((block) => block.type));
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
AnthropicClient client = new();
List mcpServers =
[
new()
{
Url = "https://example-server.modelcontextprotocol.io/sse",
Name = "example-mcp",
AuthorizationToken = "YOUR_TOKEN",
},
];
List messages =
[
new() { Role = 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.
var first = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools = [new BetaMcpToolset("example-mcp")],
Messages = messages,
});
var listing = first.Content
.Select(block => block.Value)
.OfType()
.First();
Console.WriteLine(string.Join(", ", listing.Tools.Select(tool => tool.Name)));
// Fixiere die Liste: Kopiere die Tools des Blocks in das Toolset. Die API verwendet
// genau diese Einträge und fragt den Server nicht erneut.
var second = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Betas = [AnthropicBeta.McpClient2026_09_15],
McpServers = mcpServers,
Tools =
[
new BetaMcpToolset("example-mcp")
{
Tools =
[
.. listing.Tools.Select(tool => new BetaMcpToolParam
{
Name = tool.Name,
Description = tool.Description,
InputSchema = tool.InputSchema,
}),
],
},
],
Messages = messages,
});
// Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
Console.WriteLine(string.Join(", ", second.Content.Select(block => block.Type)));
```
```go Go
client := anthropic.NewClient()
mcpServers := []anthropic.BetaRequestMCPServerURLDefinitionParam{
{
URL: "https://example-server.modelcontextprotocol.io/sse",
Name: "example-mcp",
AuthorizationToken: anthropic.String("YOUR_TOKEN"),
},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("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, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{MCPServerName: "example-mcp"}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
var listing anthropic.BetaMCPToolListingBlock
for _, block := range first.Content {
if listingBlock, ok := block.AsAny().(anthropic.BetaMCPToolListingBlock); ok {
listing = listingBlock
break
}
}
// Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Die API verwendet
// genau diese Einträge und fragt den Server nicht erneut.
var toolNames []string
var pinnedTools []anthropic.BetaMCPToolParam
for _, tool := range listing.Tools {
toolNames = append(toolNames, tool.Name)
pinnedTools = append(pinnedTools, anthropic.BetaMCPToolParam{
Name: tool.Name,
Description: anthropic.String(tool.Description),
InputSchema: tool.InputSchema,
})
}
fmt.Println(toolNames)
second, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMCPClient2026_09_15},
MCPServers: mcpServers,
Tools: []anthropic.BetaToolUnionParam{
{OfMCPToolset: &anthropic.BetaMCPToolsetParam{
MCPServerName: "example-mcp",
Tools: pinnedTools,
}},
},
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
// Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
var blockTypes []string
for _, block := range second.Content {
blockTypes = append(blockTypes, block.Type)
}
fmt.Println(blockTypes)
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMcpTool;
import com.anthropic.models.beta.messages.BetaMcpToolListingBlock;
import com.anthropic.models.beta.messages.BetaMcpToolset;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition;
import com.anthropic.models.beta.messages.MessageCreateParams;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BetaRequestMcpServerUrlDefinition mcpServer = BetaRequestMcpServerUrlDefinition.builder()
.url("https://example-server.modelcontextprotocol.io/sse")
.name("example-mcp")
.authorizationToken("YOUR_TOKEN")
.build();
// 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.
BetaMessage first = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.build())
.addUserMessage("What tools do you have available?")
.build());
BetaMcpToolListingBlock listing = first.content().stream()
.flatMap(block -> block.mcpToolListing().stream())
.findFirst()
.orElseThrow();
IO.println(listing.tools().stream().map(BetaMcpTool::name).toList());
// Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Die API verwendet
// genau diese Einträge und fragt den Server nicht erneut.
BetaMessage second = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addBeta(AnthropicBeta.MCP_CLIENT_2026_09_15)
.addMcpServer(mcpServer)
.addTool(BetaMcpToolset.builder()
.mcpServerName("example-mcp")
.tools(listing.tools().stream().map(BetaMcpTool::toParam).toList())
.build())
.addUserMessage("What tools do you have available?")
.build());
// Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
IO.println(second.content().stream()
.map(block -> block.type().asString())
.toList());
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMCPTool;
use Anthropic\Beta\Messages\BetaMCPToolListingBlock;
// ...
$client = new Client();
$mcpServers = [
[
'type' => 'url',
'url' => 'https://example-server.modelcontextprotocol.io/sse',
'name' => 'example-mcp',
'authorization_token' => 'YOUR_TOKEN',
],
];
$messages = [['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: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [['type' => 'mcp_toolset', 'mcp_server_name' => 'example-mcp']],
messages: $messages,
);
$listing = array_find($first->content, fn ($block) => $block instanceof BetaMCPToolListingBlock);
echo json_encode(array_map(fn (BetaMCPTool $tool) => $tool->name, $listing->tools)), PHP_EOL;
// Fixiere die Liste: Kopiere die Tools des Blocks ins Toolset. Die API verwendet
// genau diese Einträge und fragt den Server nicht erneut.
$second = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5_5,
maxTokens: 1024,
betas: [AnthropicBeta::MCP_CLIENT_2026_09_15],
mcpServers: $mcpServers,
tools: [
[
'type' => 'mcp_toolset',
'mcp_server_name' => 'example-mcp',
'tools' => array_map(
fn (BetaMCPTool $tool) => [
'name' => $tool->name,
'description' => $tool->description,
'input_schema' => $tool->inputSchema,
],
$listing->tools,
),
],
],
messages: $messages,
);
// Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
echo json_encode(array_map(fn ($block) => $block->type, $second->content)), PHP_EOL;
```
```ruby Ruby
client = Anthropic::Client.new
mcp_servers = [
{
type: "url",
url: "https://example-server.modelcontextprotocol.io/sse",
name: "example-mcp",
authorization_token: "YOUR_TOKEN"
}
]
messages = [{ 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: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [{ type: "mcp_toolset", mcp_server_name: "example-mcp" }],
messages:
)
listing = first.content.find { it.is_a?(Anthropic::Beta::BetaMCPToolListingBlock) }
puts listing.tools.map(&:name).inspect
# 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: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
betas: [Anthropic::AnthropicBeta::MCP_CLIENT_2026_09_15],
mcp_servers:,
tools: [
{
type: "mcp_toolset",
mcp_server_name: "example-mcp",
tools: listing.tools.map(&:to_h)
}
],
messages:
)
# Mit einem fixierten Toolset enthält die Antwort keinen mcp_tool_listing-Block.
puts second.content.map(&:type).inspect
```
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](https://platform.claude.com/docs/de/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta).
## 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:
```json
{
"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`](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#tool-configuration-options) zusammen mit dem [Tool-Search-Tool](https://platform.claude.com/docs/de/agents-and-tools/tool-use/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.
```bash
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:
```json
{
"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](https://modelcontextprotocol.io/specification/2025-11-25/basic/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), stellt das SDK 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](https://github.com/modelcontextprotocol/typescript-sdk)) zusammen mit dem Anthropic SDK verwendest.
Verwende den [`mcp_servers`-API-Parameter](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#using-the-mcp-connector-in-the-messages-api), wenn du Remote-Server hast, die per URL erreichbar sind, und nur Tool-Unterstützung benötigst. Verwende die clientseitigen Helfer, wenn du lokale Server, Prompts, Ressourcen oder mehr Kontrolle über die Verbindung mit dem Basis-SDK benötigst.
### Installation
Installiere sowohl das Anthropic SDK als auch das MCP SDK:
Die MCP-Helfer sind im Extra `mcp` enthalten, das Python 3.10 oder höher erfordert:
```bash
pip install "anthropic[mcp]"
```
```bash
npm install @anthropic-ai/sdk @modelcontextprotocol/sdk
```
Die Helfer befinden sich im separaten Paket `Anthropic.Mcp`; der MCP-Client selbst stammt aus dem offiziellen [ModelContextProtocol-Paket](https://www.nuget.org/packages/ModelContextProtocol):
```bash
dotnet add package Anthropic.Mcp
dotnet add package ModelContextProtocol
```
Die Helfer befinden sich im Unterpaket `mcp` des Go SDK, das auf dem [MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk) aufbaut:
```bash
go get github.com/anthropics/anthropic-sdk-go/mcp
```
Die Helfer befinden sich im separaten Artefakt `anthropic-java-mcp`, das Java 17 oder höher erfordert (das Basis-SDK unterstützt Java 8). Füge es zusätzlich zur Basis-Abhängigkeit `anthropic-java` hinzu:
```kotlin
implementation("com.anthropic:anthropic-java:2.73.0")
implementation("com.anthropic:anthropic-java-mcp:2.73.0")
```
```xml
com.anthropic
anthropic-java
2.73.0
com.anthropic
anthropic-java-mcp
2.73.0
```
Die Helfer verwenden das offizielle [MCP PHP SDK](https://packagist.org/packages/mcp/sdk):
```bash
composer require "anthropic-ai/sdk" "guzzlehttp/guzzle:^7" "mcp/sdk"
```
Die Helfer verwenden das offizielle [`mcp`-Gem](https://rubygems.org/gems/mcp):
```bash
bundle add anthropic mcp
```
### Verfügbare Helfer
Importiere die Helfer für deine Sprache:
```python Python
from anthropic.lib.tools.mcp import (
async_mcp_tool,
mcp_message,
mcp_resource_to_content,
mcp_resource_to_file,
)
```
```typescript TypeScript
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
```
```go Go
import (
"github.com/anthropics/anthropic-sdk-go/mcp"
)
```
```java Java
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
```
```ruby Ruby
require "anthropic"
# Die Helper werden über das Modul Anthropic::Mcp bereitgestellt
```
| Helfer | Beschreibung |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `async_mcp_tool(tool, mcp_client)` (typescript: `mcpTools(tools, mcpClient)`; csharp: `BetaMcp.ListToolsAsync(mcpClient)`; go: `mcp.NewBetaTools(tools, session)`; java: `BetaMcp.mcpTools(tools, mcpClient)`; php: `BetaMcp::tools($tools, $mcp)`; ruby: `Anthropic::Mcp.tools(tools, mcp_client)`) | Konvertiert MCP-Tools in Claude-API-Tools zur Verwendung mit `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`) |
| `mcp_message(message)` (typescript: `mcpMessages(messages)`; csharp: `BetaMcp.Messages(messages)`; go: `mcp.ToMessage(message)`; java: `BetaMcp.mcpMessages(messages)`; php: `BetaMcp::message($message)`; ruby: `Anthropic::Mcp.message(message)`) | Konvertiert MCP-Prompt-Nachrichten in das Nachrichtenformat der Claude API |
| `mcp_resource_to_content(resource)` (typescript: `mcpResourceToContent(resource)`; csharp: `BetaMcp.ResourceToContent(resource)`; go: `mcp.ResourceToBlock(resource)`; java: `BetaMcp.mcpResourceContents(resource)`; php: `BetaMcp::resourceToContent($resource)`; ruby: `Anthropic::Mcp.resource_to_contents(resource)`) | Konvertiert eine MCP-Ressource in einen Content-Block der Claude API |
| `mcp_resource_to_file(resource)` (typescript: `mcpResourceToFile(resource)`; csharp: `BetaMcp.ResourceToFile(resource)`; go: `mcp.ResourceToFile(resource)`; java: `BetaMcp.mcpResourceFiles(resource)`; php: `BetaMcp::resourceToFile($resource)`; ruby: `Anthropic::Mcp.resource_to_files(resource)`) | Konvertiert eine MCP-Ressource in ein Dateiobjekt zum Hochladen |
### MCP-Tools verwenden
Konvertiere MCP-Tools zur Verwendung mit dem [Tool-Runner](https://platform.claude.com/docs/de/agents-and-tools/tool-use/tool-runner) des SDK, der die Tool-Ausführung automatisch übernimmt:
```python Python
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())
```
```typescript TypeScript
import {
mcpTools,
type MCPCallToolResultLike,
type MCPClientLike
} from "@anthropic-ai/sdk/helpers/beta/mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const anthropic = new Anthropic();
// Verbinde dich mit einem MCP-Server
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);
// Liste Tools auf und konvertiere sie für die Claude API
const { tools } = await mcpClient.listTools();
// Der Rückgabetyp von callTool im MCP SDK enthält noch eine Legacy-Ergebnisform, die
// mcpTools nicht akzeptiert; schränke ihn ein. Entferne dies, sobald MCPClientLike erweitert wird.
const mcpClientForTools: MCPClientLike = {
callTool: (params) => mcpClient.callTool(params) as Promise
};
const finalMessage = await anthropic.beta.messages.toolRunner({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: mcpTools(tools, mcpClientForTools)
});
console.log(finalMessage);
```
```csharp C#
using Anthropic.Helpers.Beta;
using Anthropic.Helpers.Beta.Mcp;
using Anthropic.Models.Beta.Messages;
using ModelContextProtocol.Client;
using Messages = Anthropic.Models.Messages;
var anthropic = new AnthropicClient();
// Verbinde dich mit einem MCP-Server
await using var mcpClient = await McpClient.CreateAsync(
new StdioClientTransport(new StdioClientTransportOptions { Command = "mcp-server" })
);
// Liste Tools auf und konvertiere sie für die Claude API
var tools = await BetaMcp.ListToolsAsync(mcpClient);
var runner = anthropic.Beta.Messages.ToolRunner(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "What tools do you have available?",
},
],
},
tools
);
var finalMessage = await runner.RunUntilDoneAsync();
Console.WriteLine(finalMessage);
```
```go Go
import (
// ...
// ...
"github.com/anthropics/anthropic-sdk-go/mcp"
mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
)
func main() {
client := anthropic.NewClient()
ctx := context.Background()
// Verbinde dich mit einem MCP-Server
mcpClient := mcpsdk.NewClient(&mcpsdk.Implementation{Name: "my-client", Version: "1.0.0"}, nil)
session, err := mcpClient.Connect(ctx, &mcpsdk.CommandTransport{Command: exec.Command("mcp-server")}, nil)
if err != nil {
log.Fatal(err)
}
defer session.Close()
// Liste Tools auf und konvertiere sie für die Claude API
toolsResult, err := session.ListTools(ctx, nil)
if err != nil {
log.Fatal(err)
}
betaTools, err := mcp.NewBetaTools(toolsResult.Tools, session)
if err != nil {
log.Fatal(err)
}
runner := client.Beta.Messages.NewToolRunner(betaTools, anthropic.BetaToolRunnerParams{
BetaMessageNewParams: anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What tools do you have available?")),
},
},
})
finalMessage, err := runner.RunToCompletion(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println(finalMessage.RawJSON())
}
```
```java Java
import com.anthropic.helpers.BetaToolRunner;
import com.anthropic.helpers.McpBetaTool;
import com.anthropic.mcp.BetaMcp;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.client.transport.ServerParameters;
import io.modelcontextprotocol.client.transport.StdioClientTransport;
import io.modelcontextprotocol.json.McpJsonDefaults;
import io.modelcontextprotocol.spec.McpSchema;
// ...
void main() throws Exception {
AnthropicClient anthropic = AnthropicOkHttpClient.fromEnv();
// Verbinde dich mit einem MCP-Server
StdioClientTransport transport = new StdioClientTransport(
ServerParameters.builder("mcp-server").build(), McpJsonDefaults.getMapper());
try (McpSyncClient mcpClient = McpClient.sync(transport)
.clientInfo(new McpSchema.Implementation("my-client", "1.0.0"))
.build()) {
mcpClient.initialize();
// Liste Tools auf und konvertiere sie für die Claude API
List betaTools = BetaMcp.mcpTools(mcpClient.listTools().tools(), mcpClient);
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessage("What tools do you have available?")
.addTools(betaTools)
.build();
// Der Runner liefert eine Nachricht pro Assistant-Turn; die letzte ist die finale Antwort
BetaToolRunner runner = anthropic.beta().messages().toolRunner(params);
BetaMessage finalMessage = null;
for (BetaMessage message : runner) {
finalMessage = message;
}
IO.println(finalMessage);
}
}
```
```php PHP
use Anthropic\Lib\Tools\BetaMcp;
use Mcp\Client;
use Mcp\Client\Transport\HttpTransport;
$anthropic = new Anthropic();
// Verbinde dich mit einem MCP-Server. Der PHP-MCP-Client verbindet sich über HTTP; richte dies
// auf den Endpunkt deines Servers.
$mcp = Client::builder()->build();
$mcp->connect(new HttpTransport('http://localhost:8000/mcp'));
// Liste die Tools auf und konvertiere sie für die Claude API
$runner = $anthropic->beta->messages->toolRunner(
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'What tools do you have available?']],
model: 'claude-opus-5-5',
tools: BetaMcp::tools($mcp->listTools()->tools, $mcp),
);
echo $runner->runUntilDone(), "\n";
```
```ruby Ruby
require "mcp"
anthropic = Anthropic::Client.new
# Mit einem MCP-Server verbinden
transport = MCP::Client::Stdio.new(command: "mcp-server")
mcp_client = MCP::Client.new(transport: transport)
mcp_client.connect
# Tools auflisten und für die Claude API konvertieren
runner = anthropic.beta.messages.tool_runner(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "What tools do you have available?" }],
tools: Anthropic::Mcp.tools(mcp_client.tools, mcp_client)
)
final_message = runner.run_until_finished.last
puts final_message
```
### MCP-Prompts verwenden
Konvertiere MCP-Prompt-Nachrichten in das Claude-API-Nachrichtenformat:
```python Python
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)
```
```typescript TypeScript
import { mcpMessages } from "@anthropic-ai/sdk/helpers/beta/mcp";
const { messages } = await mcpClient.getPrompt({ name: "my-prompt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: mcpMessages(messages)
});
console.log(response);
```
```csharp C#
var prompt = await mcpClient.GetPromptAsync("my-prompt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = BetaMcp.Messages(prompt.Messages),
}
);
Console.WriteLine(response);
```
```go Go
prompt, err := session.GetPrompt(ctx, &mcpsdk.GetPromptParams{Name: "my-prompt"})
if err != nil {
log.Fatal(err)
}
messages := make([]anthropic.BetaMessageParam, 0, len(prompt.Messages))
for _, promptMessage := range prompt.Messages {
message, err := mcp.ToMessage(promptMessage)
if err != nil {
log.Fatal(err)
}
messages = append(messages, message)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: messages,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
McpSchema.GetPromptResult prompt = mcpClient.getPrompt(
new McpSchema.GetPromptRequest("my-prompt", Map.of()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.messages(BetaMcp.mcpMessages(prompt.messages()))
.build());
IO.println(response);
```
```php PHP
$prompt = $mcp->getPrompt('my-prompt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: array_map(BetaMcp::message(...), $prompt->messages),
model: 'claude-opus-5-5',
);
echo $response, "\n";
```
```ruby Ruby
prompt = mcp_client.get_prompt(name: "my-prompt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: prompt["messages"].map { |message| Anthropic::Mcp.message(message) }
)
puts response
```
### MCP-Ressourcen verwenden
Konvertiere MCP-Ressourcen in Content-Blöcke, um sie in Nachrichten einzubinden, oder in Dateiobjekte zum Hochladen:
```python Python
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)
```
```typescript TypeScript
import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";
// Als Content-Block in einer Nachricht
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
const response = await anthropic.beta.messages.create({
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
mcpResourceToContent(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
});
console.log(response);
// Als Datei-Upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
const uploaded = await anthropic.files.upload({ file: mcpResourceToFile(fileResource) });
console.log(uploaded.id);
```
```csharp C#
// Als Content-Block in einer Nachricht
var resource = await mcpClient.ReadResourceAsync("file:///path/to/doc.txt");
var response = await anthropic.Beta.Messages.Create(
new MessageCreateParams
{
Model = Messages::Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = new BetaMessageParamContent(
[
BetaMcp.ResourceToContent(resource),
new BetaTextBlockParam { Text = "Summarize this document" },
]
),
},
],
}
);
Console.WriteLine(response);
// Als Datei-Upload
var fileResource = await mcpClient.ReadResourceAsync("file:///path/to/data.json");
var (filename, data, mediaType) = BetaMcp.ResourceToFile(fileResource);
// Erstelle den Datei-Teil explizit, damit Dateiname und MIME-Typ der Ressource
// in den Upload übernommen werden.
var file = new BinaryContent { Stream = new MemoryStream(data), FileName = filename };
if (mediaType is not null)
{
file.ContentType = new(mediaType);
}
var uploaded = await anthropic.Files.Upload(new FileUploadParams { File = file });
Console.WriteLine(uploaded.ID);
```
```go Go
// Als Content-Block in einer Nachricht
resource, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/doc.txt"})
if err != nil {
log.Fatal(err)
}
block, err := mcp.ResourceToBlock(resource)
if err != nil {
log.Fatal(err)
}
response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
// ResourceToBlock gibt die Tool-Result-Content-Union zurück; Nachrichten-
// Content ist ein separater Union-Typ, daher die gemeinsamen Varianten neu verpacken
// (mcp.ToMessage macht intern dasselbe).
anthropic.BetaContentBlockParamUnion{
OfText: block.OfText,
OfImage: block.OfImage,
OfDocument: block.OfDocument,
},
anthropic.NewBetaTextBlock("Summarize this document"),
),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
// Als Datei-Upload
fileResult, err := session.ReadResource(ctx, &mcpsdk.ReadResourceParams{URI: "file:///path/to/data.json"})
if err != nil {
log.Fatal(err)
}
fileReader, err := mcp.ResourceToFile(fileResult)
if err != nil {
log.Fatal(err)
}
uploaded, err := client.Files.Upload(ctx, anthropic.FileUploadParams{File: fileReader})
if err != nil {
log.Fatal(err)
}
fmt.Println(uploaded.ID)
```
```java Java
// Als Content-Block in einer Nachricht
McpSchema.ReadResourceResult resource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/doc.txt"));
List content =
new ArrayList<>(BetaMcp.mcpResourceContents(resource));
content.add(BetaContentBlockParam.ofText(
BetaTextBlockParam.builder().text("Summarize this document").build()));
BetaMessage response = anthropic.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addUserMessageOfBetaContentBlockParams(content)
.build());
IO.println(response);
// Als Datei-Upload
McpSchema.ReadResourceResult fileResource = mcpClient.readResource(
new McpSchema.ReadResourceRequest("file:///path/to/data.json"));
McpResourceFile resourceFile = BetaMcp.mcpResourceFiles(fileResource).getFirst();
// Erstelle den Datei-Teil explizit, damit Dateiname und MIME-Typ der Ressource
// in den Upload übernommen werden.
MultipartField.Builder fileField = MultipartField.builder()
.value(new ByteArrayInputStream(resourceFile.content()))
.filename(resourceFile.filename());
if (resourceFile.mimeType() != null) {
fileField.contentType(resourceFile.mimeType());
}
var uploaded = anthropic.files().upload(FileUploadParams.builder()
.file(fileField.build())
.build());
IO.println(uploaded.id());
```
```php PHP
// Als Content-Block in einer Nachricht
$resource = $mcp->readResource('file:///path/to/doc.txt');
$response = $anthropic->beta->messages->create(
maxTokens: 1024,
messages: [
[
'role' => 'user',
'content' => [
BetaMcp::resourceToContent($resource),
['type' => 'text', 'text' => 'Summarize this document'],
],
],
],
model: 'claude-opus-5-5',
);
echo $response, "\n";
// Als Datei-Upload
$fileResource = $mcp->readResource('file:///path/to/data.json');
$file = $anthropic->files->upload(file: BetaMcp::resourceToFile($fileResource));
echo $file->id, "\n";
```
```ruby Ruby
# Als Content-Block in einer Nachricht
resource = mcp_client.read_resource(uri: "file:///path/to/doc.txt")
response = anthropic.beta.messages.create(
model: "claude-opus-5-5",
max_tokens: 1024,
messages: [
{
role: "user",
content: [
*Anthropic::Mcp.resource_to_contents(resource),
{ type: "text", text: "Summarize this document" }
]
}
]
)
puts response
# Als Datei-Upload
file_resource = mcp_client.read_resource(uri: "file:///path/to/data.json")
file = Anthropic::Mcp.resource_to_files(file_resource).first
uploaded_file = anthropic.files.upload(file: file)
puts uploaded_file.id
```
### Fehlerbehandlung
Die Konvertierungsfunktionen schlagen mit `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) 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](https://platform.claude.com/docs/de/build-with-claude/batch-processing) 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](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention).
## 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):**
```json
{
"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):**
```json
{
"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
| Altes Muster | Neues Muster |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Keine `tool_configuration` (alle Tools aktiviert) | MCPToolset ohne `default_config` oder `configs` |
| `tool_configuration.enabled: false` | MCPToolset mit `default_config.enabled: false` |
| `tool_configuration.allowed_tools: [...]` | MCPToolset mit `default_config.enabled: false` und bestimmten in `configs` aktivierten Tools |
## Abgekündigte Version: mcp-client-2025-04-04
Diese Version ist abgekündigt. Migriere mithilfe des vorangehenden [Migrationsleitfadens](https://platform.claude.com/docs/de/agents-and-tools/mcp-connector#migration-guide) auf `mcp-client-2025-11-20`.
Die vorherige Version des MCP-Connectors enthielt die Tool-Konfiguration direkt in der MCP-Server-Definition:
```json
{
"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
| Eigenschaft | Typ | Beschreibung |
| ---------------------------------- | ------- | -------------------------------------------------------------------------- |
| `tool_configuration` | object | **Abgekündigt:** Verwende stattdessen MCPToolset im `tools`-Array |
| `tool_configuration.enabled` | boolean | **Abgekündigt:** Verwende `default_config.enabled` im MCPToolset |
| `tool_configuration.allowed_tools` | array | **Abgekündigt:** Verwende das Allowlist-Muster mit `configs` im MCPToolset |