MCP-Connector

Claudes Model Context Protocol (MCP) Connector-Funktion ermöglicht es Ihnen, sich direkt von der Messages API aus mit Remote-MCP-Servern zu verbinden, ohne einen separaten MCP-Client zu implementieren.

Wichtigste Funktionen

• Direkte API-Integration: Verbinden Sie sich mit MCP-Servern, ohne einen MCP-Client zu implementieren
• Tool-Calling-Unterstützung: Greifen Sie auf MCP-Tools über die Messages API zu
• Flexible Tool-Konfiguration: Aktivieren Sie alle Tools, erstellen Sie eine Allowlist für bestimmte Tools oder erstellen Sie eine Denylist für unerwünschte Tools
• Pro-Tool-Konfiguration: Konfigurieren Sie einzelne Tools mit benutzerdefinierten Einstellungen
• OAuth-Authentifizierung: Unterstützung für OAuth Bearer Tokens für authentifizierte Server
• Mehrere Server: Verbinden Sie sich mit mehreren MCP-Servern in einer einzigen Anfrage

Einschränkungen

• Von den Funktionen der MCP-Spezifikation werden derzeit nur Tool Calls unterstützt.
• Der Server muss öffentlich über HTTP verfügbar gemacht werden (unterstützt sowohl Streamable HTTP als auch SSE-Transporte). Lokale STDIO-Server können nicht direkt verbunden werden.
• Der MCP-Connector wird derzeit nicht auf Amazon Bedrock und Google Vertex unterstützt.

Verwendung des MCP-Connectors in der Messages API

Der MCP-Connector verwendet zwei Komponenten:

1. MCP-Serverdefinition (mcp_servers Array): Definiert die Serververbindungsdetails (URL, Authentifizierung)
2. MCP-Toolset (tools Array): Konfiguriert, welche Tools aktiviert werden sollen und wie sie konfiguriert werden sollen

Grundlegendes Beispiel

Dieses Beispiel aktiviert alle Tools von einem MCP-Server mit Standardkonfiguration:

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",
    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-Serverkonfiguration

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 vom MCP-Server aktiviert sind und wie sie konfiguriert werden sollen.

Grundlegende Struktur

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

Für das vollständige Verzeichnis von Anthropic-bereitgestellten Tools und optionalen Eigenschaften wie defer_loading siehe die Tool-Referenz. Zum Durchsuchen großer Tool-Sets siehe Tool Search Tool.

Konfigurationsmerging

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

1. Tool-spezifische Einstellungen in configs
2. Set-Level default_config
3. Systemstandards

Beispiel:

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

Ergibt:

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

Häufige Konfigurationsmuster

Alle Tools mit Standardkonfiguration aktivieren

Das einfachste Muster - aktivieren Sie alle Tools von einem Server:

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

Allowlist - Nur bestimmte Tools aktivieren

Setzen Sie enabled: false als Standard, aktivieren Sie 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

Aktivieren Sie alle Tools standardmäßig, deaktivieren Sie dann explizit unerwünschte Tools:

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

Gemischt - Allowlist mit Pro-Tool-Konfiguration

Kombinieren Sie 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 einem Server entsprechen, der im mcp_servers Array definiert ist
• Server muss verwendet werden: Jeder MCP-Server, der im mcp_servers Array definiert ist, 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 nicht auf dem MCP-Server existiert, wird eine Backend-Warnung protokolliert, aber es wird kein Fehler zurückgegeben (MCP-Server können 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

Sie können sich mit mehreren MCP-Servern verbinden, indem Sie mehrere Serverdefinitionen in mcp_servers und ein entsprechendes MCPToolset für jeden im tools Array einfügen:

{
  "model": "claude-opus-4-7",
  "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
      }
    }
  ]
}

Authentifizierung

Für MCP-Server, die OAuth-Authentifizierung erfordern, müssen Sie ein Zugriffstoken abrufen. Der MCP-Connector-Beta unterstützt die Übergabe eines authorization_token Parameters in der MCP-Serverdefinition. API-Verbraucher werden erwartet, den OAuth-Flow zu handhaben und das Zugriffstoken vor dem API-Aufruf zu erhalten, sowie das Token bei Bedarf zu aktualisieren.

Abrufen eines Zugriffstokens zum Testen

Der MCP-Inspector kann Sie durch den Prozess des Abrufens eines Zugriffstokens zu Testzwecken führen.

1. Führen Sie den Inspector mit dem folgenden Befehl aus. Sie benötigen Node.js auf Ihrem Computer installiert.

   npx @modelcontextprotocol/inspector

2. Wählen Sie in der linken Seitenleiste für "Transport type" entweder "SSE" oder "Streamable HTTP".

3. Geben Sie die URL des MCP-Servers ein.

4. Klicken Sie im rechten Bereich auf die Schaltfläche "Open Auth Settings" nach "Need to configure authentication?".

5. Klicken Sie auf "Quick OAuth Flow" und autorisieren Sie auf dem OAuth-Bildschirm.

6. Folgen Sie den Schritten im Abschnitt "OAuth Flow Progress" des Inspectors und klicken Sie auf "Continue", bis Sie "Authentication complete" erreichen.

7. Kopieren Sie den access_token Wert.

8. Fügen Sie ihn in das authorization_token Feld in Ihrer MCP-Serverkonfiguration ein.

Verwendung des Zugriffstokens

Sobald Sie ein Zugriffstoken mit einem der obigen OAuth-Flows erhalten haben, können Sie es in Ihrer MCP-Serverkonfiguration verwenden:

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

Für detaillierte Erklärungen des OAuth-Flows siehe den Abschnitt Authorization in der MCP-Spezifikation.

Client-seitige MCP-Helfer (TypeScript)

Wenn Sie Ihre eigene MCP-Client-Verbindung verwalten (z. B. mit lokalen Stdio-Servern, MCP-Prompts oder MCP-Ressourcen), bietet das TypeScript SDK Hilfsfunktionen, die zwischen MCP-Typen und Claude API-Typen konvertieren. Dies eliminiert manuellen Konvertierungscode bei der Verwendung des MCP SDK zusammen mit dem Anthropic SDK.

Installation

Installieren Sie sowohl das Anthropic SDK als auch das MCP SDK:

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

Verfügbare Helfer

Importieren Sie die Helfer aus dem Beta-Namespace:

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

MCP-Tools verwenden

Konvertieren Sie MCP-Tools zur Verwendung mit dem Tool Runner des SDK, der die Tool-Ausführung automatisch handhabt:

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();

// Connect to an 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);

// List tools and convert them for the Claude API
const { tools } = await mcpClient.listTools();
const runner = await anthropic.beta.messages.toolRunner({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

MCP-Prompts verwenden

Konvertieren Sie MCP-Prompt-Nachrichten in 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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

MCP-Ressourcen verwenden

Konvertieren Sie MCP-Ressourcen in Content-Blöcke, um sie in Nachrichten einzubeziehen, oder in Dateiobjects zum Hochladen:

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

// As a content block in a message
const resource = await mcpClient.readResource({ uri: "file:///path/to/doc.txt" });
await anthropic.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: [
        mcpResourceToContent(resource),
        { type: "text", text: "Summarize this document" }
      ]
    }
  ]
});

// As a file 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 nicht von der Claude API unterstützt wird. Dies kann bei nicht unterstützten Inhaltstypen, MIME-Typen oder Nicht-HTTP-Ressourcen-Links auftreten.

Datenspeicherung

Der MCP-Connector ist nicht durch ZDR-Vereinbarungen abgedeckt. Daten, die mit MCP-Servern ausgetauscht werden, einschließlich Tool-Definitionen und Ausführungsergebnisse, werden gemäß der Standard-Datenspeicherungsrichtlinie von Anthropic beibehalten.

Für ZDR-Berechtigung über alle Funktionen hinweg siehe API und Datenspeicherung.

Migrationsleitfaden

Wenn Sie den veralteten mcp-client-2025-04-04 Beta-Header verwenden, folgen Sie diesem Leitfaden, um zur neuen Version zu migrieren.

Wichtigste Änderungen

1. Neuer Beta-Header: Ändern Sie von mcp-client-2025-04-04 zu mcp-client-2025-11-20
2. Tool-Konfiguration verschoben: Tool-Konfiguration befindet sich jetzt im tools Array als MCPToolset-Objekte, nicht in der MCP-Serverdefinition
3. Flexiblere Konfiguration: Neues Muster unterstützt Allowlisting, Denylisting und Pro-Tool-Konfiguration

Migrationsschritte

Vorher (veraltet):

{
  "model": "claude-opus-4-7",
  "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-7",
  "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
        }
      }
    }
  ]
}

Häufige Migrationsmuster

Veraltete Version: mcp-client-2025-04-04

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

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