mcp-client-2025-04-04の移行 — tool_configurationをMCPToolsetへ

MCPコネクタを旧ベータヘッダーmcp-client-2025-04-04のまま使っているなら、直す箇所は3つです。ヘッダーをmcp-client-2025-11-20に替える。mcp_servers内のtool_configurationを消す。同じ内容をtools配列のmcp_toolsetに書き直す。

MCPコネクタは、別途MCPクライアントを実装しなくてもMessages APIからリモートMCPサーバーへ接続できる機能です。旧版は、ツールの有効・無効を接続先サーバーの定義に直接書いていました。新版はそれを分離し、サーバー定義と「どのツールをどう使うか」を別のオブジェクトにしています。

何が変わるのか

変更点は3つです。

接続情報の側(type / url / name / authorization_token)は書き換え不要です。サーバー側の項目は旧版と同じ形のまま残ります。

旧版ページのtool_configuration、tool_configuration.enabled、tool_configuration.allowed_toolsには、いずれも「非推奨」と明記されています。移行先もそれぞれ決まっています。

書き換えの実例

許可リストで2つのツールだけを有効にしている旧リクエストを例にします。

旧版(非推奨)では、サーバー定義の中に設定が入っていました。

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

新版では、サーバー定義からtool_configurationを外します。代わりにtools配列へmcp_toolsetを置き、mcp_server_nameでサーバーを指します。

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

ここで注意したいのは、allowed_toolsに当たる専用フィールドが新版には無い点です。「既定は無効にして、使うツールだけ有効にする」という2段の書き方に変わります。default_config.enabledをfalseにし忘れると、configsに2つ書いても全ツールが有効なままになります。enabledの既定値がtrueだからです。

ヘッダーの差し替えは、curlなら1行です。

# 変更前
-H "anthropic-beta: mcp-client-2025-04-04"
# 変更後
-H "anthropic-beta: mcp-client-2025-11-20"

SDKではbetas引数に渡す値を替えます。Pythonならbetas=["mcp-client-2025-11-20"]の形です。

移行の手順

旧設定のパターン別の写し方

旧版の書き方ごとに、新版での対応が決まっています。

1行目に注意が要ります。旧版で設定を書いていなかったサーバーも、新版ではmcp_toolsetが必要です。最小形は次のとおりです。

{ "type": "mcp_toolset", "mcp_server_name": "example-mcp" }

理由は検証ルールにあります。mcp_serversに定義した各サーバーは、ちょうど1つのmcp_toolsetから参照されなければなりません。mcp_server_nameが存在しないサーバーを指す場合も、検証で弾かれます。複数サーバーを繋いでいるコードでは、サーバーの数だけmcp_toolsetが要ります。

新版で追加された書き方

旧版の機能だけを移すなら、ここまでで終わりです。新版ではさらに2つのことができます。

拒否リスト

特定のツールだけを止めるには、default_configは触らず、configsで対象をenabled: falseにします。

{
  "type": "mcp_toolset",
  "mcp_server_name": "example-mcp",
  "configs": {
    "delete_record": { "enabled": false }
  }
}

設定の優先順位は、configsのツール個別設定、default_config、システム既定値の順です。個別設定が常に勝ちます。許可リストと拒否リストは同じ仕組みの裏表で、既定を有効にするか無効にするかの違いです。

ツール単位のdefer_loading

defer_loadingをtrueにすると、そのツールの説明は最初にはモデルへ送られません。ツール検索ツールと組み合わせて使う設定です。default_configに置けば全ツールに、configsに置けば特定のツールにだけ効きます。ツール数が多いサーバーを複数繋ぐ場合に検討する項目です。

複数サーバーを繋いでいる場合

サーバーが2つ以上あるリクエストでは、旧版は各サーバー定義に設定を持たせていました。新版はmcp_serversにサーバーを並べ、toolsにサーバーごとのmcp_toolsetを並べます。

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

nameはサーバーごとに一意でなければならず、1つのnameを指せるmcp_toolsetは1つだけです。旧版の設定をサーバーごとに分けて持っていたコードは、そのままmcp_toolsetの配列に展開できます。ツール数が増えるほど、サーバー単位のdefault_configでdefer_loadingを切り替える意味が出てきます。

対応する提供面とバッチ処理

新版のページでは、ベータ機能として提供される面にClaude API、Claude Platform on AWS、Microsoft Foundryが挙がっています。ZDRは対象外と表示されています。

Message Batches APIのリクエストにもmcp_serversを含められます。その場合のMCPツール呼び出しの料金は、通常のMessages APIと同じです。バッチ処理で旧ヘッダーを使っているジョブがあれば、同じ書き換えが必要です。

ローカルのSTDIOサーバーや、MCPのプロンプト・リソースを使いたい場合は、コネクタではなくSDKのクライアント側ヘルパーが受け皿になります。自前でMCPクライアント接続を持ち、MCPの型とClaude APIの型をSDKが変換する方式です。コネクタの移行とは別の選択肢です。

移行後に変わらないこと

レスポンス側のmcp_tool_useとmcp_tool_resultというコンテンツブロックは、新版のページにも載っています。mcp_tool_useには呼び出したツールのname、入力のinput、どのサーバーかを示すserver_nameが入ります。mcp_tool_resultはtool_use_idで呼び出しと結び付き、失敗したかどうかをis_errorで示します。複数サーバーを繋ぐ構成でも、server_nameを見れば呼び出し元を判別できます。結果を処理するコードの側は、移行のために直す箇所として挙がっていません。認証も同じで、OAuthトークンの取得とリフレッシュは呼び出し側の責任です。トークンはauthorization_tokenに渡します。

制約も新版のページに残っています。

• サーバーはHTTPで公開されている必要があり、StreamableHTTPとSSEの両方に対応します。ローカルのSTDIOサーバーには直接つなげません
• MCP仕様の機能のうち、サポートされるのはツール呼び出しだけです
• ZDR(ゼロデータリテンション)の対象外です。ツール定義や実行結果は通常のデータ保持ポリシーに従います

SSEについては、MCP仕様側でHTTP+SSEトランスポートが非推奨になっています。コネクタのドキュメント例のURLが/sseで終わっていても、接続先サーバーのトランスポートを見直す話は別です。詳しくはMCPのHTTP+SSEの非推奨にあります。

2026-09-15のベータヘッダーとの関係

mcp-client-2025-11-20の次のヘッダーとして、mcp-client-2026-09-15があります。サーバーが返したツール一覧を記録し、mcp_toolsetのtoolsに固定できるベータ機能です。mcp-client-2025-11-20の内容をすべて含むので、使うときは置き換えで送ります。Claude APIで使えます。

このヘッダーを使うと、レスポンスの先頭にmcp_tool_listingブロックが付くことがあります。content[0]を前提にした処理は、このブロックを読み飛ばす必要があります。アシスタントのメッセージを次のリクエストに戻すときは、このブロックも含めたまま送ります。

旧版から移る場合は、まずmcp-client-2025-11-20への移行を済ませるのが筋です。固定機能が必要になった時点で、ヘッダーだけを替えれば済みます。mcp_toolsetの形が同じだからです。

旧ヘッダーはいつまで動くのか

旧版のページには「非推奨」の警告があり、移行ガイドへ誘導されています。一方、この節には終了日の記載がありません。非推奨の旧ヘッダーがいつ使えなくなるかは、ドキュメントからは読み取れません。

終了日が書かれていないからといって、放置できる材料にはなりません。コネクタ全体がベータ機能で、ヘッダー名自体に日付が入っています。日付付きヘッダーは世代交代を前提にした仕組みです。新しい書き方に寄せておけば、世代が替わるときの差分が小さくて済みます。

移行後の確認

書き換えたら、次の3点を確かめます。

1. 各mcp_serversのnameが、ちょうど1つのmcp_toolsetのmcp_server_nameと一致している
2. 許可リストだった箇所で、default_config.enabledがfalseになっている
3. 旧ヘッダーの文字列がコードベースに残っていない

2つ目は、動くけれど意図と違う状態になりやすい箇所です。確認用に、ツール一覧を尋ねるだけのリクエストを送ります。

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 @request.json

request.jsonには、移行後のボディを入れます。OAuth認証が要るサーバーでテスト用のトークンが手元に無いときは、npx @modelcontextprotocol/inspectorでQuick OAuth Flowを実行するとaccess_tokenを取得できます。それをauthorization_tokenに貼れば、移行後の形で動作を確かめられます。質問文は「使えるツールを挙げて」程度で足ります。返ってきた一覧に、許可したはずのないツールが混ざっていれば、default_configの設定漏れを疑います。

なお、configsのキーに存在しないツール名を書いても、エラーにはなりません。バックエンドで警告が記録されるだけです。MCPサーバー側のツールが動的に変わりうるための仕様です。つまり、ツール名の綴りを間違えても、リクエストは通ります。許可したつもりのツールが使えない場合は、綴りを疑います。

まとめ

移行の実体は、設定の置き場所の引っ越しです。ヘッダーを替え、tool_configurationをmcp_toolsetに写し、設定なしのサーバーにもmcp_toolsetを足す。この3つで済みます。

見落としやすいのは、許可リストをdefault_config.enabled: falseで表す点と、設定のなかったサーバーにもmcp_toolsetが要る点です。Messages API全体の中でのコネクタの位置づけは、Anthropic API完全ガイドにまとまっています。非推奨になったMCP機能を横断して把握したいときは、MCPの非推奨機能一覧が入口になります。