メッセージMCP

MCPコネクタ

Claudeの「Model Context Protocol」、すなわちMCPのコネクタ機能を使用すると、別途MCPクライアントを用意することなく、Messages APIから直接リモートMCPサーバーに接続できます。

現在のバージョン： この機能にはベータヘッダー "anthropic-beta": "mcp-client-2025-11-20" が必要です。

以前のバージョン（mcp-client-2025-04-04）は非推奨です。非推奨バージョン：mcp-client-2025-04-04を参照してください。

この機能はZero Data Retention (ZDR)の対象外です。データは、この機能の標準的な保持ポリシーに従って保持されます。

主な機能

直接API統合：MCPクライアントを実装せずにMCPサーバーに接続
ツール呼び出しのサポート：Messages APIを通じてMCPツールにアクセス
柔軟なツール設定：すべてのツールを有効化、特定のツールを許可リストに追加、または不要なツールを拒否リストに追加
ツールごとの設定：個々のツールをカスタム設定で構成
OAuth認証：認証が必要なサーバー向けのOAuth Bearerトークンをサポート
複数サーバー：単一のリクエストで複数のMCPサーバーに接続

ClaudeがMCPツールを使用するタイミング

MCPサーバーが接続されると、ユーザーのリクエストがツールの記述された機能に対応する場合、Claudeはそのツールを呼び出します。これは明示的な場合（「Jiraでオープンなバグを検索して」）も、暗黙的な場合（Jiraサーバーが接続された状態で「リリースを妨げているものは何？」）もあります。

Claudeは、接続されたサービスに関する一般的な知識の質問に対してはMCPツールを呼び出しません。Notionサーバーが接続された状態で「Notionデータベースはどのように機能しますか？」と尋ねた場合は直接回答されますが、「私のProjectsデータベースには何がありますか？」と尋ねるとツールがトリガーされます。

システムプロンプトを通じて、ClaudeがMCPツールをどの程度積極的に呼び出すかを調整できます。一般的なガイダンスと例文については、Claudeがツールを使用するタイミングを参照してください。

制限事項

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

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

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

MCPサーバー定義（mcp_servers配列）：サーバー接続の詳細（URL、認証）を定義
MCPツールセット（tools配列）：有効にするツールとその設定方法を構成

基本的な例

この例では、デフォルト設定でMCPサーバーのすべてのツールを有効にします。

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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サーバー設定

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

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は以下の検証ルールを適用します。

サーバーが存在すること：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-8",
  "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
      }
    }
  ]
}

多数のツールが利用可能な場合、Claudeはツール名と説明に基づいて選択します。明確で具体的なツールの説明により、選択の精度が向上します。大規模なツールセット（複数のサーバーにわたる数十のツール）の場合は、ツール検索ツールと併せてdefer_loadingを有効にすることを検討してください。これにより、クエリごとに関連するツールのみが表示されます。

認証

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仕様のAuthorizationセクションを参照してください。

クライアントサイドMCPヘルパー

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

これらのヘルパーは、Python、TypeScript、Java、Go、Ruby、PHPのSDKで利用できます。C# SDKではまだ利用できません。このセクションの例はTypeScriptを使用しています。他の言語では、以下から同等のヘルパーをインポートしてください。

Python： anthropic.lib.tools.mcp（pip install anthropic[mcp]でインストール）
Java： anthropic-java-mcpモジュール内のcom.anthropic.mcp.BetaMcp
Go： github.com/anthropics/anthropic-sdk-go/mcp
Ruby： Anthropic::Mcp（mcp gemが必要）
PHP： Anthropic\Lib\Tools\BetaMcp

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

MCPツールの使用

MCPツールを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 finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

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-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

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-opus-4-8",
  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以外のリソースリンクで発生する可能性があります。

バッチリクエスト

Message Batches APIリクエストにmcp_serversを含めることができます。Batches APIを通じたMCPツール呼び出しは、通常のMessages APIリクエストと同じ料金で課金されます。

データ保持

MCPコネクタはZDR契約の対象外です。ツール定義や実行結果を含む、MCPサーバーと交換されるデータは、Anthropicの標準データ保持ポリシーに従って保持されます。

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

移行ガイド

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

主な変更点

新しいベータヘッダー：mcp-client-2025-04-04からmcp-client-2025-11-20に変更
ツール設定の移動：ツール設定は、MCPサーバー定義内ではなく、tools配列内のMCPToolsetオブジェクトに配置されるようになりました
より柔軟な設定：新しいパターンは、許可リスト、拒否リスト、およびツールごとの設定をサポートします

移行手順

移行前（非推奨）：

{
  "model": "claude-opus-4-8",
  "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-8",
  "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`を使用した許可リストパターンを使用してください

Was this page helpful?

メッセージMCP

MCPコネクタ

現在のバージョン： この機能にはベータヘッダー "anthropic-beta": "mcp-client-2025-11-20" が必要です。

以前のバージョン（mcp-client-2025-04-04）は非推奨です。非推奨バージョン：mcp-client-2025-04-04を参照してください。

この機能はZero Data Retention (ZDR)の対象外です。データは、この機能の標準的な保持ポリシーに従って保持されます。

主な機能

直接API統合：MCPクライアントを実装せずにMCPサーバーに接続
ツール呼び出しのサポート：Messages APIを通じてMCPツールにアクセス
柔軟なツール設定：すべてのツールを有効化、特定のツールを許可リストに追加、または不要なツールを拒否リストに追加
ツールごとの設定：個々のツールをカスタム設定で構成
OAuth認証：認証が必要なサーバー向けのOAuth Bearerトークンをサポート
複数サーバー：単一のリクエストで複数のMCPサーバーに接続

ClaudeがMCPツールを使用するタイミング

制限事項

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

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

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

MCPサーバー定義（mcp_servers配列）：サーバー接続の詳細（URL、認証）を定義
MCPツールセット（tools配列）：有効にするツールとその設定方法を構成

基本的な例

この例では、デフォルト設定でMCPサーバーのすべてのツールを有効にします。

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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サーバー設定

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

許可リスト：特定のツールのみを有効化

デフォルトとして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は以下の検証ルールを適用します。

サーバーが存在すること：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-8",
  "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仕様のAuthorizationセクションを参照してください。

クライアントサイドMCPヘルパー

Python： anthropic.lib.tools.mcp（pip install anthropic[mcp]でインストール）
Java： anthropic-java-mcpモジュール内のcom.anthropic.mcp.BetaMcp
Go： github.com/anthropics/anthropic-sdk-go/mcp
Ruby： Anthropic::Mcp（mcp gemが必要）
PHP： Anthropic\Lib\Tools\BetaMcp

インストール

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ツールの使用

MCPツールを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 finalMessage = await anthropic.beta.messages.toolRunner({
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{ role: "user", content: "What tools do you have available?" }],
  tools: mcpTools(tools, mcpClient)
});

console.log(finalMessage);

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-opus-4-8",
  max_tokens: 1024,
  messages: mcpMessages(messages)
});

console.log(response);

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-opus-4-8",
  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オブジェクトに配置されるようになりました
より柔軟な設定：新しいパターンは、許可リスト、拒否リスト、およびツールごとの設定をサポートします

移行手順

移行前（非推奨）：

{
  "model": "claude-opus-4-8",
  "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-8",
  "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`を使用した許可リストパターンを使用してください

Was this page helpful?

主な機能

ClaudeがMCPツールを使用するタイミング

制限事項

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

基本的な例

MCPサーバー設定

フィールドの説明

MCPツールセット設定

基本構造

フィールドの説明

ツール設定オプション

設定のマージ

一般的な設定パターン

デフォルト設定ですべてのツールを有効化

許可リスト：特定のツールのみを有効化

拒否リスト：特定のツールを無効化

混合：ツールごとの設定を伴う許可リスト

検証ルール

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

MCPツール使用ブロック

MCPツール結果ブロック

複数のMCPサーバー

認証

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

アクセストークンの使用

クライアントサイドMCPヘルパー

インストール

利用可能なヘルパー

MCPツールの使用

MCPプロンプトの使用

MCPリソースの使用

エラー処理

バッチリクエスト

データ保持

移行ガイド

主な変更点

移行手順

一般的な移行パターン

非推奨バージョン：mcp-client-2025-04-04

非推奨フィールドの説明

主な機能

ClaudeがMCPツールを使用するタイミング

制限事項

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

基本的な例

MCPサーバー設定

フィールドの説明

MCPツールセット設定

基本構造

フィールドの説明

ツール設定オプション

設定のマージ

一般的な設定パターン

デフォルト設定ですべてのツールを有効化

許可リスト：特定のツールのみを有効化

拒否リスト：特定のツールを無効化

混合：ツールごとの設定を伴う許可リスト

検証ルール

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

MCPツール使用ブロック

MCPツール結果ブロック

複数のMCPサーバー

認証

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

アクセストークンの使用

クライアントサイドMCPヘルパー

インストール

利用可能なヘルパー

MCPツールの使用

MCPプロンプトの使用

MCPリソースの使用

エラー処理

バッチリクエスト

データ保持

移行ガイド

主な変更点

移行手順

一般的な移行パターン

非推奨バージョン：mcp-client-2025-04-04

非推奨フィールドの説明

主な機能

ClaudeがMCPツールを使用するタイミング

制限事項

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

基本的な例

MCPサーバー設定

フィールドの説明

MCPツールセット設定

基本構造

フィールドの説明

ツール設定オプション

設定のマージ

一般的な設定パターン

デフォルト設定ですべてのツールを有効化

許可リスト：特定のツールのみを有効化

拒否リスト：特定のツールを無効化

混合：ツールごとの設定を伴う許可リスト

検証ルール

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

MCPツール使用ブロック

MCPツール結果ブロック

複数のMCPサーバー

認証

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

アクセストークンの使用

クライアントサイドMCPヘルパー

インストール

利用可能なヘルパー

MCPツールの使用

MCPプロンプトの使用

MCPリソースの使用

エラー処理

バッチリクエスト

データ保持

移行ガイド

主な変更点

移行手順

一般的な移行パターン

非推奨バージョン：mcp-client-2025-04-04

非推奨フィールドの説明

主な機能

ClaudeがMCPツールを使用するタイミング

制限事項

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

基本的な例

MCPサーバー設定

フィールドの説明

MCPツールセット設定

基本構造

フィールドの説明

ツール設定オプション

設定のマージ

一般的な設定パターン

デフォルト設定ですべてのツールを有効化

許可リスト：特定のツールのみを有効化

拒否リスト：特定のツールを無効化

混合：ツールごとの設定を伴う許可リスト

検証ルール

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

MCPツール使用ブロック

MCPツール結果ブロック

複数のMCPサーバー

認証

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

アクセストークンの使用

クライアントサイドMCPヘルパー

インストール

利用可能なヘルパー

MCPツールの使用

MCPプロンプトの使用

MCPリソースの使用

エラー処理

バッチリクエスト

データ保持

移行ガイド

主な変更点

移行手順

一般的な移行パターン

非推奨バージョン：mcp-client-2025-04-04

非推奨フィールドの説明