MCP-Connector

Das Model Context Protocol (MCP) Connector-Feature von Claude ermöglicht es Ihnen, sich direkt über die Messages API mit Remote-MCP-Servern zu verbinden, ohne einen separaten MCP-Client zu benötigen.

Hauptfunktionen

• Direkte API-Integration: Verbinden Sie sich mit MCP-Servern ohne Implementierung eines MCP-Clients
• Tool-Calling-Unterstützung: Zugriff auf MCP-Tools über die Messages API
• Flexible Tool-Konfiguration: Alle Tools aktivieren, bestimmte Tools auf eine Allowlist setzen oder unerwünschte Tools auf eine Denylist setzen
• Konfiguration pro Tool: Einzelne Tools mit benutzerdefinierten Einstellungen konfigurieren
• OAuth-Authentifizierung: Unterstützung für OAuth Bearer-Tokens für authentifizierte Server
• Mehrere Server: Verbindung zu mehreren MCP-Servern in einer einzigen Anfrage

Einschränkungen

• Vom Funktionsumfang der MCP-Spezifikation werden derzeit nur Tool-Aufrufe unterstützt.
• Der Server muss öffentlich über HTTP zugänglich sein (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-Server-Definition (mcp_servers-Array): Definiert Server-Verbindungsdetails (URL, Authentifizierung)
2. MCP-Toolset (tools-Array): Konfiguriert, welche Tools aktiviert werden sollen und wie sie konfiguriert werden

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

Konfigurationszusammenführung

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 – alle Tools von einem Server aktivieren:

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

Allowlist – Nur bestimmte Tools aktivieren

enabled: false als Standard setzen, dann bestimmte Tools explizit aktivieren:

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

Alle Tools standardmäßig aktivieren, dann unerwünschte Tools explizit deaktivieren:

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

Gemischt – Allowlist mit Tool-spezifischer Konfiguration

Allowlisting mit benutzerdefinierter Konfiguration für jedes Tool kombinieren:

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

In diesem Beispiel:

• search_events ist aktiviert mit defer_loading: false
• list_events ist aktiviert mit defer_loading: true (von default_config geerbt)
• Alle anderen Tools sind deaktiviert

Validierungsregeln

Die API erzwingt diese Validierungsregeln:

• Server muss existieren: Der mcp_server_name in einem MCPToolset muss mit einem 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 nicht auf dem MCP-Server existiert, wird eine Backend-Warnung protokolliert, aber 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 Inhaltsblock-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 Server-Definitionen in mcp_servers und ein entsprechendes MCPToolset für jeden im tools-Array einfügen:

{
  "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 erhalten. Die MCP-Connector-Beta unterstützt die Übergabe eines authorization_token-Parameters in der MCP-Server-Definition. API-Nutzer sind dafür verantwortlich, den OAuth-Flow zu verwalten und das Zugriffstoken vor dem API-Aufruf zu erhalten sowie das Token bei Bedarf zu erneuern.

Zugriffstoken für Tests erhalten

Der MCP-Inspector kann Sie durch den Prozess der Beschaffung eines Zugriffstokens für Testzwecke führen.

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

   npx @modelcontextprotocol/inspector

2. Wählen Sie in der linken Seitenleiste unter "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 Feld authorization_token in Ihrer MCP-Server-Konfiguration ein.

Das Zugriffstoken verwenden

Sobald Sie ein Zugriffstoken über den oben beschriebenen OAuth-Flow erhalten haben, können Sie es in Ihrer MCP-Server-Konfiguration verwenden:

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

Ausführliche Erläuterungen zum OAuth-Flow finden Sie im Autorisierungsabschnitt der MCP-Spezifikation.

Client-seitige MCP-Hilfsfunktionen (TypeScript)

Wenn Sie Ihre eigene MCP-Client-Verbindung verwalten (z. B. mit lokalen stdio-Servern, MCP-Prompts oder MCP-Ressourcen), stellt das TypeScript-SDK Hilfsfunktionen bereit, 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 Hilfsfunktionen

Importieren Sie die Hilfsfunktionen 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 verwaltet:

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

// Mit einem MCP-Server verbinden
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// Tools auflisten und für die Claude API konvertieren
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 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-sonnet-4-6",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

MCP-Ressourcen verwenden

Konvertieren Sie MCP-Ressourcen in Inhaltsblöcke zur Einbindung in Nachrichten 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-sonnet-4-6",
  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 Inhaltstypen, MIME-Typen oder Nicht-HTTP-Ressourcenlinks 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 aufbewahrt.

Informationen zur ZDR-Berechtigung für alle Features finden Sie unter API und Datenspeicherung.

Migrationsleitfaden

Wenn Sie den veralteten mcp-client-2025-04-04-Beta-Header verwenden, folgen Sie diesem Leitfaden zur Migration auf die neue Version.

Wesentliche Änderungen

1. Neuer Beta-Header: Wechseln Sie von mcp-client-2025-04-04 zu mcp-client-2025-11-20
2. Tool-Konfiguration verschoben: Die Tool-Konfiguration befindet sich jetzt im tools-Array als MCPToolset-Objekte, nicht in der MCP-Server-Definition
3. Flexiblere Konfiguration: Das neue Muster unterstützt Allowlisting, Denylisting und Tool-spezifische 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-Server-Definition:

{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://example-server.modelcontextprotocol.io/sse",
      "name": "example-mcp",
      "authorization_token": "YOUR_TOKEN",
      "tool_configuration": {
        "enabled": true,
        "allowed_tools": ["example_tool_1", "example_tool_2"]
      }
    }
  ]
}

Veraltete Feldbeschreibungen