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-Token für authentifizierte Server
• Mehrere Server: Verbinden Sie sich mit mehreren MCP-Servern in einer einzelnen Anfrage

Einschränkungen

• Von der Funktionsgruppe der MCP-Spezifikation werden derzeit nur Tool-Aufrufe 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 Verbindungsdetails (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:

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-4-6",
    "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"
      }
    ]
  }'

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:

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

Ergebnisse in:

• 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

Aktivieren Sie alle Tools mit Standardkonfiguration

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

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

Allowlist - Aktivieren Sie nur bestimmte Tools

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 - Deaktivieren Sie bestimmte Tools

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 mit defer_loading: false aktiviert
• list_events ist mit defer_loading: true aktiviert (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 Inhaltsblocktypen:

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 einschließen:

{
  "model": "claude-opus-4-6",
  "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 abzurufen, 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 Inspektors und klicken Sie auf "Continue", bis Sie "Authentication complete" erreichen.

7. Kopieren Sie den access_token-Wert.

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

Verwendung des Zugriffstokens

Nachdem Sie ein Zugriffstoken mit einem der obigen OAuth-Flows abgerufen 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"
    }
  ]
}

Detaillierte Erklärungen des OAuth-Flows finden Sie im 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 neben 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";

Verwenden Sie MCP-Tools

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

import Anthropic from "@anthropic-ai/sdk";
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)
});

Verwenden Sie MCP-Prompts

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

Verwenden Sie MCP-Ressourcen

Konvertieren Sie MCP-Ressourcen in Inhaltsblöcke, um sie in Nachrichten einzuschließen, oder in Dateiobjekte 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-Ressourcenlinks auftreten.

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

Beschreibungen veralteter Felder