Claude Media
Claude APIのMCPコネクタ — mcp_toolsetでリモートMCPを繋ぐ
ClaudeMCPClaude連携チュートリアル

Claude APIのMCPコネクタ — mcp_toolsetでリモートMCPを繋ぐ

Messages APIにmcp_serversとmcp_toolsetを書くと、MCPクライアントなしでリモートサーバーのツールを使えます。allowlist・denylist、検証ルール、公開HTTPのみという制約を確認します。

読了目安 約20分

Claude APIのMCPコネクタは、MCPクライアントなしでリモートサーバーを繋ぐ機能

MCPコネクタは、Messages APIのリクエストにMCPサーバーの接続情報を書くだけで、そのサーバーのツールをClaudeに使わせる機能です。MCPクライアントを自分で実装する必要はありません。現在はベータで、ベータヘッダーはmcp-client-2025-11-20です。対応プラットフォームの表記は、Claude API・Claude Platform on AWS・Microsoft Foundryがいずれもベータになっています。

仕組みは2つの部品で成り立ちます。

  • mcp_servers配列: 接続先のURLと認証を定義する
  • tools配列のmcp_toolset: どのツールを有効にするかを定義する

この2つは必ず対で書きます。MCPの概念そのものはMCPとはで扱っています。Managed Agents側の接続方法はManaged AgentsのMCP接続を設定しvaultで認証する手順にあります。ここではMessages APIを直接叩く場合に絞ります。

最小構成はmcp_serversとmcp_toolsetを1組書くだけ

全ツールを有効にする最小のリクエストは次のとおりです。

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

SDKを使う場合も形は同じで、Pythonならclient.beta.messages.createにmcp_servers・tools・betas=["mcp-client-2025-11-20"]を渡します。

mcp_serversの各要素のフィールドは次の4つです。

フィールド必須内容
type必須必須内容現在は"url"のみ
url必須必須内容MCPサーバーのURL。https://で始まる必要がある
name必須必須内容サーバーの一意な識別子。tools内のMCPToolsetちょうど1つから参照される
authorization_token必須任意内容サーバーがOAuthを求める場合のトークン

mcp_toolset側はtypeとmcp_server_nameが必須で、default_config・configs・cache_controlが任意です。mcp_server_nameはmcp_serversのどれかのnameと一致させます。

繋げるのは公開HTTPのサーバーだけで、使えるのはツール呼び出しだけ

制限事項は2つあります。

  1. MCP仕様の機能のうち、対応するのはツール呼び出しだけです。プロンプトやリソースは、このコネクタ経由では扱えません。
  2. サーバーはHTTPで公開されている必要があります。トランスポートはStreamable HTTPとSSEの両方に対応します。ローカルのSTDIOサーバーは直接繋げません。

urlがhttps://で始まる必要があることも合わせると、社内ネットワークの中だけで動くサーバーや、手元でnpx起動するサーバーはそのままでは対象外です。こうしたサーバーやMCPのプロンプト・リソースを使いたい場合に備えて、SDKにはクライアント側のヘルパー関数が用意されています。自分でMCPクライアント接続を持ち、MCPの型をClaude APIの型へ変換する用途で、コネクタとは別の経路です。

もう1点、データの扱いにも注意が要ります。MCPコネクタはZDR(ゼロデータリテンション)の対象外です。ツール定義や実行結果を含め、MCPサーバーとやり取りしたデータは標準のデータ保持ポリシーに従って保持されます。

allowlistとdenylistはdefault_configとconfigsで書き分ける

ツールの絞り込みはmcp_toolsetの2つのフィールドで表現します。default_configはセット内の全ツールの既定値、configsはツール名をキーにした個別の上書きです。各ツールが持つ設定はenabled(既定true)とdefer_loading(既定false)の2つです。

優先順位は、configsの個別設定、default_config、システム既定の順です。たとえばdefault_configでdefer_loading: trueを指定し、configsでsearch_eventsだけenabled: falseにすると、search_eventsは無効のまま、それ以外は有効かつ遅延ロードになります。

allowlist: 既定を無効にして必要なものだけ有効にする

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

書き込み系や破壊的なツールをdenylistに入れる使い方は、読み取り専用のアシスタントを作るときや、状態を変える前に人間の確認を挟みたいときに向くとされています。

併用: allowlistにツールごとの設定を足す

default_configでenabled: falseとdefer_loading: trueを指定し、configsでsearch_eventsをenabled: true, defer_loading: false、list_eventsをenabled: trueとします。結果は次のとおりです。

  • search_events: 有効、遅延なし
  • list_events: 有効、遅延あり(default_configを継承)
  • ほかのツール: すべて無効

サーバーのツールが増える可能性があるなら、denylistよりallowlistのほうが事故を防ぎやすい構成です。サーバー側で新しい書き込みツールが追加されても、allowlistなら自動では有効になりません。

検証ルールは3つ、ツール名の打ち間違いだけは弾かれない

APIが強制する検証は次のとおりです。

  • mcp_toolsetのmcp_server_nameは、mcp_serversに定義されたサーバーと一致する
  • mcp_serversに定義したサーバーは、必ずちょうど1つのMCPToolsetから参照される
  • 1つのMCPサーバーを参照できるMCPToolsetは1つだけ

「定義したのに使っていない」サーバーが許されない点は、テスト中にサーバー定義だけ残してtools側を消したときに効いてきます。同じサーバーに別の絞り込みを掛けた2つのツールセットを並べる書き方もできません。

一方、configsのキーに書いたツール名がサーバーに存在しなくても、エラーは返りません。バックエンドで警告がログに残るだけです。MCPサーバーはツールが動的に増減しうるため、という理由が示されています。

この仕様には落とし穴があります。allowlistでcreate_eventをcreate_evnetと書き間違えると、エラーにならないまま、そのツールは有効になりません。denylistで書き間違えれば、止めたつもりのツールが有効のまま残ります。API側から指摘が来ない以上、リクエスト後の確認が必要です。

呼ばれたツールはmcp_tool_useブロックで確認する

ClaudeがMCPツールを使うと、レスポンスに2種類のブロックが入ります。

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

mcp_tool_resultはtool_use_idで呼び出しに対応し、is_errorとcontentを持ちます。mcp_tool_useのserver_nameで、どのサーバーのツールかを判別できます。

allowlist・denylistの設定を検証するには、呼ばれたくないツールを呼ばせる依頼をしてブロックを数える方法が手軽です。次はPythonでの確認用スケッチです(型の持ち方は公式のSDK例に沿った一例です)。

resp = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1000,
    messages=[{"role": "user", "content": "来週の予定をすべて削除して"}],
    mcp_servers=[{"type": "url", "url": "https://mcp.example.com/sse",
                  "name": "google-calendar-mcp"}],
    tools=[{"type": "mcp_toolset",
            "mcp_server_name": "google-calendar-mcp",
            "configs": {"delete_all_events": {"enabled": False}}}],
    betas=["mcp-client-2025-11-20"],
)
used = [b.name for b in resp.content if b.type == "mcp_tool_use"]
print(used)  # delete_all_events が含まれていないことを確認する

「What tools do you have available?」と聞く方法も、一覧の目視確認には使えます。ただしこれはモデルの回答なので、設定の反映確認というよりサーバーに繋がっているかの確認と捉えるほうが安全です。

ツール一覧を固定したいならmcp-client-2026-09-15ベータを使う

MCPサーバーはいつでもツールを変えられます。会話の途中で一覧が変わると、Claudeに見えるツールも変わります。mcp-client-2026-09-15ベータヘッダーは、この一覧を記録して固定する仕組みです。mcp-client-2025-11-20の機能をすべて含むため、置き換えて送ります。利用可能なのはClaude APIです。

動きは次の2段階です。

  1. 一覧を固定していない状態でAPIがサーバーにツールを問い合わせると、レスポンスの先頭にそのサーバーのmcp_tool_listingブロックが入る
  2. そのブロックのtoolsをMCPToolsetのtoolsフィールドへ写すと、APIはサーバーに問い合わせず、そのエントリだけがツールになる(default_configとconfigsは適用される)

各エントリは、サーバーが返すツール名(サーバー名なし)・description・input_schemaを持ちます。アシスタントのメッセージを次のリクエストに返すときは、mcp_tool_listingブロックを含めたまま、毎回mcp-client-2026-09-15を送ります。コードでcontent[0]を読んでいる場合は、先頭にmcp_tool_listingが来るため読み飛ばす処理が要ります。

authorization_tokenはAPI利用者が取得して更新する

OAuthが必要なサーバーでは、アクセストークンの取得と更新をAPI利用者が担います。コネクタが行うのは、渡されたトークンを使うことだけです。

テスト用のトークンは、MCP inspectorで取れます。

npx @modelcontextprotocol/inspector

左のサイドバーでTransport typeにSSEかStreamable HTTPを選び、サーバーのURLを入れます。Open Auth SettingsからQuick OAuth Flowを実行し、Authentication completeまで進めたら、access_tokenの値をauthorization_tokenに貼ります。本番では更新の仕組みを自前で持つ必要があるため、トークンの期限切れで呼び出しが失敗する経路はアプリ側で処理します。

複数サーバーはサーバーごとにツールセットを足し、ツールが多ければ遅延ロードを併用する

複数のサーバーを同時に繋ぐ場合は、mcp_serversに定義を並べ、toolsに対応するツールセットをサーバーの数だけ置きます。サーバーごとにdefault_configを変えられるので、片方は全ツールを通常ロード、もう片方はdefer_loading: true、という分け方ができます。

ツールが数十個を超えるような構成では、defer_loadingとTool search toolの併用が勧められています。MCP経由のツールには、個々の定義にdefer_loadingを書けません。mcp_toolsetのdefault_configかconfigsに書きます。キャッシュとの関係はdefer_loadingでプロンプトキャッシュを壊さずツールを追加する仕組みで扱っています。

Message Batches APIのリクエストにもmcp_serversを含められ、MCPツール呼び出しの料金は通常のMessages APIと変わりません。

2025-04-04版からの移行は、tool_configurationをmcp_toolsetへ移すだけ

旧ベータmcp-client-2025-04-04は非推奨です。変更点は、ベータヘッダーの差し替えと、ツール設定の置き場がmcp_servers内のtool_configurationからtools配列のMCPToolsetへ移ったことの2つです。

旧パターン新パターン
tool_configurationなし(全ツール有効)新パターンdefault_config・configsなしのMCPToolset
tool_configuration.enabled: false新パターンdefault_config.enabled: false
tool_configuration.allowed_tools: [...]新パターンdefault_config.enabled: falseと、configsで個別に有効化

mcp_serversからtool_configurationを消し、同じnameをmcp_server_nameに持つMCPToolsetをtoolsに足す作業です。ツール名のバージョン付き命名(_YYYYMMDD)との関係はClaude APIツールのバージョン管理の読み方で扱っています。

まとめ

MCPコネクタの設計の肝は、サーバー定義とツール選択を分け、両者を1対1で結ぶ点にあります。作業としては、まずhttps://で公開されたサーバーを用意し、toolsetをallowlistで書き始め、レスポンスのmcp_tool_useで意図どおりか確かめる流れが堅実です。ツールの打ち間違いがエラーにならない以上、確認工程が設定の一部になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude をもっと見る →