MCP-Connector

Claudes „Model Context Protocol" (MCP)-Connector-Funktion ermöglicht es dir, direkt über die Messages API eine Verbindung zu Remote-MCP-Servern herzustellen, 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, erlaube nur bestimmte Tools per Allowlist oder schließe unerwünschte Tools per Denylist aus
• 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 („suche in 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.
• Der MCP-Connector ist über die Claude API, Claude Platform on AWS und Microsoft Foundry verfügbar. Er ist derzeit nicht auf Amazon Bedrock oder Vertex AI verfügbar.



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-4-8",
    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 folgender Priorität zusammengeführt (höchste zuerst):

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

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 erstellst 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 (geerbt von default_config)
• 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 ein entsprechendes MCPToolset für jeden im tools-Array angibst:

{
  "model": "claude-opus-4-8",
  "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 defer_loading mit dem Tool-Search-Tool 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 linken Seitenleiste bei „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 mit einem der vorangegangenen 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"
    }
  ]
}

Detaillierte Erklärungen zum OAuth-Flow findest du im Abschnitt Authorization der MCP-Spezifikation.



Clientseitige MCP-Helper (TypeScript)

Wenn du deine eigene MCP-Client-Verbindung verwaltest (zum Beispiel mit lokalen stdio-Servern, MCP-Prompts oder MCP-Ressourcen), bietet das TypeScript-SDK Hilfsfunktionen, die zwischen MCP-Typen und Claude-API-Typen konvertieren. Dies erspart manuellen Konvertierungscode, wenn du das MCP-SDK zusammen mit dem Anthropic-SDK verwendest.



Installation

Installiere sowohl das Anthropic-SDK als auch das MCP-SDK:

npm install @anthropic-ai/sdk @modelcontextprotocol/sdk



Verfügbare Helper

Importiere die Helper aus dem Beta-Namespace:

import {
  mcpTools,
  mcpMessages,
  mcpResourceToContent,
  mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";



MCP-Tools verwenden

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

import { mcpTools } 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 die Tools auf und konvertiere sie für die Claude API
const { tools } = await mcpClient.listTools();
const finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);



MCP-Prompts verwenden

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

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-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);



MCP-Ressourcen verwenden

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

import { mcpResourceToContent, mcpResourceToFile } from "@anthropic-ai/sdk/helpers/beta/mcp";

// Als Inhaltsblock in einer Nachricht
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// Als Datei-Upload
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });



Fehlerbehandlung

Die Konvertierungsfunktionen werfen UnsupportedMCPValueError, wenn ein MCP-Wert von der Claude API nicht unterstützt wird. Dies kann bei nicht unterstützten Content-Typen, MIME-Typen oder Nicht-HTTP-Ressourcenlinks passieren.



Batch-Anfragen

Du kannst mcp_servers in Anfragen an die Message Batches API 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äß der Standard-Datenaufbewahrungsrichtlinie von Anthropic aufbewahrt.

Informationen zur ZDR-Berechtigung für alle Funktionen findest du unter API und Datenaufbewahrung.



Migrationsleitfaden

Wenn du den veralteten Beta-Header mcp-client-2025-04-04 verwendest, folge diesem Leitfaden, um zur neuen 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 mehr 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-4-8",
  "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-4-8",
  "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"]
      }
    }
  ]
}



Beschreibungen veralteter Felder