ClaudeのModel Context Protocol(MCP)コネクタ機能により、別のMCPクライアントを実装することなく、Messages APIから直接リモートMCPサーバーに接続できます。
現在のバージョン: この機能にはベータヘッダーが必要です: "anthropic-beta": "mcp-client-2025-11-20"
前のバージョン(mcp-client-2025-04-04)は非推奨です。以下の非推奨バージョンドキュメントを参照してください。
This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.
MCPコネクタは2つのコンポーネントを使用します:
mcp_servers配列): サーバー接続詳細(URL、認証)を定義tools配列): 有効にするツールと設定方法を設定この例は、デフォルト設定でMCPサーバーからすべてのツールを有効化します:
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_servers配列内の各MCPサーバーは接続詳細を定義します:
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "example-mcp",
"authorization_token": "YOUR_TOKEN"
}| プロパティ | 型 | 必須 | 説明 |
|---|---|---|---|
type | string | はい | 現在、"url"のみがサポートされています |
url | string | はい | MCPサーバーのURL。https://で始まる必要があります |
name | string | はい | このMCPサーバーの一意の識別子。tools配列内のMCPToolsetによって正確に1回参照される必要があります。 |
authorization_token | string | いいえ | MCPサーバーで必要な場合のOAuth認可トークン。MCP仕様を参照してください。 |
MCPToolsetはtools配列内に存在し、MCPサーバーからどのツールが有効化されるか、およびそれらがどのように設定されるかを設定します。
{
"type": "mcp_toolset",
"mcp_server_name": "example-mcp",
"default_config": {
"enabled": true,
"defer_loading": false
},
"configs": {
"specific_tool_name": {
"enabled": true,
"defer_loading": true
}
}
}| プロパティ | 型 | 必須 | 説明 |
|---|---|---|---|
type | string | はい | "mcp_toolset"である必要があります |
mcp_server_name | string | はい | mcp_servers配列で定義されたサーバー名と一致する必要があります |
default_config | object | いいえ | このセット内のすべてのツールに適用されるデフォルト設定。configs内の個別のツール設定がこれらのデフォルトをオーバーライドします。 |
configs | object | いいえ | ツール単位の設定オーバーライド。キーはツール名、値は設定オブジェクトです。 |
cache_control | object | いいえ | このツールセットのキャッシュブレークポイント設定 |
各ツール(default_configまたはconfigsで設定されているかどうかに関わらず)は以下のフィールドをサポートします:
| プロパティ | 型 | デフォルト | 説明 |
|---|---|---|---|
enabled | boolean | true | このツールが有効かどうか |
defer_loading | boolean | false | trueの場合、ツール説明は最初にモデルに送信されません。ツール検索ツールで使用されます。 |
Anthropic提供ツールの完全なディレクトリとdefer_loadingなどのオプションプロパティについては、ツールリファレンスを参照してください。大規模なツールセット全体での検索については、ツール検索ツールを参照してください。
設定値は以下の優先度(高から低)でマージされます:
configs内のツール固有の設定default_config例:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"defer_loading": true
},
"configs": {
"search_events": {
"enabled": false
}
}
}結果:
search_events: enabled: false(configsから)、defer_loading: true(default_configから)enabled: true(システムデフォルト)、defer_loading: true(default_configから)最もシンプルなパターン - サーバーからすべてのツールを有効化:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp"
}enabled: falseをデフォルトとして設定し、特定のツールを明示的に有効化:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"default_config": {
"enabled": false
},
"configs": {
"search_events": {
"enabled": true
},
"create_event": {
"enabled": true
}
}
}デフォルトですべてのツールを有効化し、不要なツールを明示的に無効化:
{
"type": "mcp_toolset",
"mcp_server_name": "google-calendar-mcp",
"configs": {
"delete_all_events": {
"enabled": false
},
"share_calendar_publicly": {
"enabled": false
}
}
}ホワイトリスト化と各ツールのカスタム設定を組み合わせ:
{
"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
}
}
}この例では:
search_eventsはdefer_loading: falseで有効化されていますlist_eventsはdefer_loading: trueで有効化されています(default_configから継承)APIは以下の検証ルールを適用します:
mcp_server_nameはmcp_servers配列で定義されたサーバーと一致する必要がありますmcp_serversで定義されたすべてのMCPサーバーは正確に1つのMCPToolsetによって参照される必要がありますconfigs内のツール名がMCPサーバーに存在しない場合、バックエンド警告がログに記録されますがエラーは返されません(MCPサーバーは動的なツール可用性を持つ可能性があります)ClaudeがMCPツールを使用する場合、レスポンスには2つの新しいコンテンツブロックタイプが含まれます:
{
"type": "mcp_tool_use",
"id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"name": "echo",
"server_name": "example-mcp",
"input": { "param1": "value1", "param2": "value2" }
}{
"type": "mcp_tool_result",
"tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
"is_error": false,
"content": [
{
"type": "text",
"text": "Hello"
}
]
}mcp_serversに複数のサーバー定義を含め、tools配列内の各サーバーに対応するMCPToolsetを含めることで、複数のMCPサーバーに接続できます:
{
"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
}
}
]
}OAuth認証が必要なMCPサーバーの場合、アクセストークンを取得する必要があります。MCPコネクタベータはMCPサーバー定義でauthorization_tokenパラメータを渡すことをサポートしています。
APIコンシューマーはOAuthフローを処理し、APIコールを行う前にアクセストークンを取得し、必要に応じてトークンをリフレッシュすることが期待されます。
MCPインスペクタは、テスト目的でアクセストークンを取得するプロセスをガイドできます。
以下のコマンドでインスペクタを実行します。マシンにNode.jsがインストールされている必要があります。
npx @modelcontextprotocol/inspector左側のサイドバーで、「Transport type」に対して「SSE」または「Streamable HTTP」を選択します。
MCPサーバーのURLを入力します。
右側の領域で、「Need to configure authentication?」の後の「Open Auth Settings」ボタンをクリックします。
「Quick OAuth Flow」をクリックし、OAuthスクリーンで認可します。
インスペクタの「OAuth Flow Progress」セクションのステップに従い、「Authentication complete」に到達するまで「Continue」をクリックします。
access_token値をコピーします。
MCPサーバー設定のauthorization_tokenフィールドに貼り付けます。
上記のいずれかのOAuthフローを使用してアクセストークンを取得したら、MCPサーバー設定で使用できます:
{
"mcp_servers": [
{
"type": "url",
"url": "https://example-server.modelcontextprotocol.io/sse",
"name": "authenticated-server",
"authorization_token": "YOUR_ACCESS_TOKEN_HERE"
}
]
}OAuthフローの詳細な説明については、MCP仕様の認可セクションを参照してください。
独自のMCPクライアント接続を管理する場合(例えば、ローカルstdioサーバー、MCPプロンプト、またはMCPリソース)、TypeScript SDKはMCPタイプとClaude APIタイプ間の変換を行うヘルパー関数を提供します。これにより、MCP SDKをAnthropicSDKと一緒に使用する場合の手動変換コードが不要になります。
これらのヘルパーは現在、TypeScript SDKでのみ利用可能です。
URLを通じてアクセス可能なリモートサーバーがあり、ツールサポートのみが必要な場合は、mcp_servers APIパラメータを使用します。ローカルサーバー、プロンプト、リソース、またはベースSDKとの接続をより詳細に制御する必要がある場合は、クライアント側ヘルパーを使用します。
Anthropic SDKとMCP SDKの両方をインストール:
npm install @anthropic-ai/sdk @modelcontextprotocol/sdkベータネームスペースからヘルパーをインポート:
import {
mcpTools,
mcpMessages,
mcpResourceToContent,
mcpResourceToFile
} from "@anthropic-ai/sdk/helpers/beta/mcp";| ヘルパー | 説明 |
|---|---|
mcpTools(tools, mcpClient) | MCPツールをClaude APIツールに変換してclient.beta.messages.toolRunner()で使用 |
mcpMessages(messages) | MCPプロンプトメッセージをClaude APIメッセージ形式に変換 |
mcpResourceToContent(resource) | MCPリソースをClaude APIコンテンツブロックに変換 |
mcpResourceToFile(resource) | MCPリソースをアップロード用のファイルオブジェクトに変換 |
SDKのツールランナーで使用するためにMCPツールを変換します。これはツール実行を自動的に処理します:
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プロンプトメッセージをClaude APIメッセージ形式に変換:
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リソースをコンテンツブロックに変換してメッセージに含めるか、アップロード用のファイルオブジェクトに変換:
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) });変換関数は、MCPの値がClaude APIでサポートされていない場合、UnsupportedMCPValueErrorをスロー します。これは、サポートされていないコンテンツタイプ、MIMEタイプ、または非HTTPリソースリンクで発生する可能性があります。
MCPコネクタはZDR契約の対象ではありません。MCPサーバーと交換されるデータ(ツール定義と実行結果を含む)は、Anthropicの標準データ保持ポリシーに従って保持されます。
すべての機能にわたるZDR適格性については、API とデータ保持を参照してください。
非推奨のmcp-client-2025-04-04ベータヘッダーを使用している場合は、このガイドに従って新しいバージョンにマイグレーションしてください。
mcp-client-2025-04-04からmcp-client-2025-11-20に変更tools配列内のMCPToolsetオブジェクトとして存在するようになりました前(非推奨):
{
"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"]
}
}
]
}後(現在):
{
"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
}
}
}
]
}| 古いパターン | 新しいパターン |
|---|---|
tool_configurationなし(すべてのツールが有効) | default_configまたはconfigsなしのMCPToolset |
tool_configuration.enabled: false | default_config.enabled: falseを持つMCPToolset |
tool_configuration.allowed_tools: [...] | default_config.enabled: falseとconfigsで特定のツールが有効なMCPToolset |
このバージョンは非推奨です。上記のマイグレーションガイドを使用してmcp-client-2025-11-20にマイグレーションしてください。
MCPコネクタの前のバージョンはMCPサーバー定義に直接ツール設定を含めていました:
{
"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"]
}
}
]
}| プロパティ | 型 | 説明 |
|---|---|---|
tool_configuration | object | 非推奨: tools配列内のMCPToolsetを使用してください |
tool_configuration.enabled | boolean | 非推奨: MCPToolset内のdefault_config.enabledを使用してください |
tool_configuration.allowed_tools | array | 非推奨: MCPToolset内のconfigsを使用したホワイトリストパターンを使用してください |
Was this page helpful?