API での MCP

MCPコネクター

Messages APIからリモートMCPサーバーに直接接続するためのClaudeのModel Context Protocol（MCP）コネクター機能。

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.

主な機能

直接API統合: MCPクライアントを実装せずにMCPサーバーに接続
ツール呼び出しサポート: Messages APIを通じてMCPツールにアクセス
柔軟なツール設定: すべてのツールを有効化、特定のツールをallowlist、不要なツールをdenylist
ツールごとの設定: カスタム設定で個々のツールを設定
OAuth認証: 認証済みサーバー向けのOAuth Bearerトークンのサポート
複数サーバー: 1つのリクエストで複数のMCPサーバーに接続

制限事項

MCP仕様の機能セットのうち、現在はツール呼び出しのみがサポートされています。
サーバーはHTTPを通じて公開されている必要があります（Streamable HTTPとSSEトランスポートの両方をサポート）。ローカルのSTDIOサーバーは直接接続できません。
MCPコネクターは現在、Amazon BedrockおよびGoogle Vertexではサポートされていません。

Messages APIでのMCPコネクターの使用

MCPコネクターは2つのコンポーネントを使用します:

MCPサーバー定義（mcp_servers配列）: サーバー接続の詳細（URL、認証）を定義
MCPツールセット（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サーバーの設定

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`配列内の正確に1つのMCPToolsetから参照される必要があります。
`authorization_token`	string	いいえ	MCPサーバーで必要な場合のOAuth認証トークン。MCP仕様を参照。

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の場合、ツールの説明は最初にモデルに送信されません。ツール検索ツールと共に使用します。

設定のマージ

設定値は以下の優先順位でマージされます（高い順）:

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

Allowlist - 特定のツールのみを有効化

デフォルトでenabled: falseを設定し、特定のツールを明示的に有効にします:

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

Denylist - 特定のツールを無効化

デフォルトですべてのツールを有効にし、不要なツールを明示的に無効にします:

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

混合 - ツールごとの設定を持つAllowlist

各ツールのカスタム設定とallowlistingを組み合わせます:

{
  "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はこれらのバリデーションルールを適用します:

サーバーが存在する必要がある: MCPToolset内のmcp_server_nameはmcp_servers配列で定義されたサーバーと一致する必要があります
サーバーが使用される必要がある: mcp_serversで定義されたすべてのMCPサーバーは正確に1つのMCPToolsetから参照される必要があります
サーバーごとに一意のツールセット: 各MCPサーバーは1つのMCPToolsetからのみ参照できます
不明なツール名: configs内のツール名がMCPサーバーに存在しない場合、バックエンドの警告がログに記録されますがエラーは返されません（MCPサーバーは動的なツールの可用性を持つ場合があります）

レスポンスコンテンツタイプ

ClaudeがMCPツールを使用すると、レスポンスには2つの新しいコンテンツブロックタイプが含まれます:

MCPツール使用ブロック

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCPツール結果ブロック

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

複数のMCPサーバー

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コンシューマーは、APIコールを行う前にOAuthフローを処理してアクセストークンを取得し、必要に応じてトークンを更新することが期待されています。

テスト用アクセストークンの取得

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ヘルパー（TypeScript）

独自のMCPクライアント接続を管理する場合（例: ローカルstdioサーバー、MCPプロンプト、またはMCPリソース）、TypeScript SDKはMCPタイプとClaude APIタイプ間の変換を行うヘルパー関数を提供します。これにより、MCP SDKをAnthropic SDKと共に使用する際の手動変換コードが不要になります。

これらのヘルパーは現在TypeScript SDKでのみ利用可能です。

URLを通じてアクセス可能なリモートサーバーがあり、ツールサポートのみが必要な場合は、mcp_servers APIパラメーターを使用してください。Agent SDKを使用している場合、MCP接続は自動的に管理されます。ローカルサーバー、プロンプト、リソース、またはベース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ツールを`client.beta.messages.toolRunner()`で使用するためのClaude APIツールに変換
`mcpMessages(messages)`	MCPプロンプトメッセージをClaude APIメッセージ形式に変換
`mcpResourceToContent(resource)`	MCPリソースをClaude APIコンテンツブロックに変換
`mcpResourceToFile(resource)`	MCPリソースをアップロード用のファイルオブジェクトに変換

MCPツールの使用

SDKのツールランナーで使用するためにMCPツールを変換します。ツールランナーはツールの実行を自動的に処理します:

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

// MCPサーバーに接続
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// ツールをリストアップして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プロンプトの使用

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リソースの使用

MCPリソースをメッセージに含めるコンテンツブロックに変換するか、アップロード用のファイルオブジェクトに変換します:

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

// メッセージ内のコンテンツブロックとして
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" }
      ]
    }
  ]
});

// ファイルアップロードとして
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に変更
ツール設定の移動: ツール設定はMCPサーバー定義ではなく、tools配列内のMCPToolsetオブジェクトに移動
より柔軟な設定: 新しいパターンはallowlisting、denylisting、およびツールごとの設定をサポート

移行手順

移行前（非推奨）:

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

このバージョンは非推奨です。上記の移行ガイドを使用して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`でallowlistパターンを使用してください

Was this page helpful?

API での MCP

MCPコネクター

Messages APIからリモートMCPサーバーに直接接続するためのClaudeのModel Context Protocol（MCP）コネクター機能。

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.

主な機能

直接API統合: MCPクライアントを実装せずにMCPサーバーに接続
ツール呼び出しサポート: Messages APIを通じてMCPツールにアクセス
柔軟なツール設定: すべてのツールを有効化、特定のツールをallowlist、不要なツールをdenylist
ツールごとの設定: カスタム設定で個々のツールを設定
OAuth認証: 認証済みサーバー向けのOAuth Bearerトークンのサポート
複数サーバー: 1つのリクエストで複数のMCPサーバーに接続

制限事項

MCP仕様の機能セットのうち、現在はツール呼び出しのみがサポートされています。
サーバーはHTTPを通じて公開されている必要があります（Streamable HTTPとSSEトランスポートの両方をサポート）。ローカルのSTDIOサーバーは直接接続できません。
MCPコネクターは現在、Amazon BedrockおよびGoogle Vertexではサポートされていません。

Messages APIでのMCPコネクターの使用

MCPコネクターは2つのコンポーネントを使用します:

MCPサーバー定義（mcp_servers配列）: サーバー接続の詳細（URL、認証）を定義
MCPツールセット（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サーバーの設定

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`配列内の正確に1つのMCPToolsetから参照される必要があります。
`authorization_token`	string	いいえ	MCPサーバーで必要な場合のOAuth認証トークン。MCP仕様を参照。

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の場合、ツールの説明は最初にモデルに送信されません。ツール検索ツールと共に使用します。

設定のマージ

設定値は以下の優先順位でマージされます（高い順）:

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

Allowlist - 特定のツールのみを有効化

デフォルトでenabled: falseを設定し、特定のツールを明示的に有効にします:

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

Denylist - 特定のツールを無効化

デフォルトですべてのツールを有効にし、不要なツールを明示的に無効にします:

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

混合 - ツールごとの設定を持つAllowlist

各ツールのカスタム設定とallowlistingを組み合わせます:

{
  "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はこれらのバリデーションルールを適用します:

サーバーが存在する必要がある: MCPToolset内のmcp_server_nameはmcp_servers配列で定義されたサーバーと一致する必要があります
サーバーが使用される必要がある: mcp_serversで定義されたすべてのMCPサーバーは正確に1つのMCPToolsetから参照される必要があります
サーバーごとに一意のツールセット: 各MCPサーバーは1つのMCPToolsetからのみ参照できます
不明なツール名: configs内のツール名がMCPサーバーに存在しない場合、バックエンドの警告がログに記録されますがエラーは返されません（MCPサーバーは動的なツールの可用性を持つ場合があります）

レスポンスコンテンツタイプ

ClaudeがMCPツールを使用すると、レスポンスには2つの新しいコンテンツブロックタイプが含まれます:

MCPツール使用ブロック

{
  "type": "mcp_tool_use",
  "id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "name": "echo",
  "server_name": "example-mcp",
  "input": { "param1": "value1", "param2": "value2" }
}

MCPツール結果ブロック

{
  "type": "mcp_tool_result",
  "tool_use_id": "mcptoolu_014Q35RayjACSWkSj4X2yov1",
  "is_error": false,
  "content": [
    {
      "type": "text",
      "text": "Hello"
    }
  ]
}

複数のMCPサーバー

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

認証

テスト用アクセストークンの取得

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ヘルパー（TypeScript）

これらのヘルパーは現在TypeScript 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ツールを`client.beta.messages.toolRunner()`で使用するためのClaude APIツールに変換
`mcpMessages(messages)`	MCPプロンプトメッセージをClaude APIメッセージ形式に変換
`mcpResourceToContent(resource)`	MCPリソースをClaude APIコンテンツブロックに変換
`mcpResourceToFile(resource)`	MCPリソースをアップロード用のファイルオブジェクトに変換

MCPツールの使用

SDKのツールランナーで使用するためにMCPツールを変換します。ツールランナーはツールの実行を自動的に処理します:

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

// MCPサーバーに接続
const transport = new StdioClientTransport({ command: "mcp-server", args: [] });
const mcpClient = new Client({ name: "my-client", version: "1.0.0" });
await mcpClient.connect(transport);

// ツールをリストアップして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プロンプトの使用

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リソースの使用

MCPリソースをメッセージに含めるコンテンツブロックに変換するか、アップロード用のファイルオブジェクトに変換します:

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

// メッセージ内のコンテンツブロックとして
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" }
      ]
    }
  ]
});

// ファイルアップロードとして
const fileResource = await mcpClient.readResource({ uri: "file:///path/to/data.json" });
await anthropic.beta.files.upload({ file: mcpResourceToFile(fileResource) });

エラー処理

データ保持

すべての機能にわたるZDRの適格性については、APIとデータ保持を参照してください。

移行ガイド

非推奨のmcp-client-2025-04-04ベータヘッダーを使用している場合は、このガイドに従って新しいバージョンに移行してください。

主な変更点

新しいベータヘッダー: mcp-client-2025-04-04からmcp-client-2025-11-20に変更
ツール設定の移動: ツール設定はMCPサーバー定義ではなく、tools配列内のMCPToolsetオブジェクトに移動
より柔軟な設定: 新しいパターンはallowlisting、denylisting、およびツールごとの設定をサポート

移行手順

移行前（非推奨）:

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

このバージョンは非推奨です。上記の移行ガイドを使用して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`でallowlistパターンを使用してください

Was this page helpful?