MCPのツール定義はなぜコンテキストを圧迫するのか — Tool Searchが必要になった理由

この記事は、MCPのツール定義がコンテキストを圧迫する仕組みとTool SearchのAPI側の数値を扱います。Claude CodeでのalwaysLoadやENABLE_TOOL_SEARCHの設定手順はMCPのトークンオーバーヘッドを抑える設定にまとめています。

MCPサーバーを増やすと何が起きるか

MCPサーバーを1つ繋ぐたびに、そのサーバーが持つツールの定義(名前・説明文・引数のスキーマ)がまるごとClaudeのコンテキストに送られます。公式ドキュメントは、これを放置したときの実測値を具体的な数字で示しています。GitHub・Slack・Sentry・Grafana・Splunkという典型的な5サーバー構成では、Claudeが何も作業を始める前の時点で約55,000トークンがツール定義だけで消費されます。

ツール定義は毎回のリクエストに含まれる入力トークンとして扱われます。つまり会話が何ターン続いても、繋いだMCPサーバーの数に応じた固定コストが毎回積み上がる計算です。プロンプトキャッシュが効いていれば単価は下がりますが、コンテキストウィンドウという有限の枠を消費していること自体は変わりません。

ツール定義が多いと選択精度そのものも落ちる

コンテキスト消費とは別に、もう1つ独立した問題があります。ツールの数が増えるほど、Claudeがそのなかから正しいツールを選ぶ精度が下がるという問題です。公式ドキュメントは「利用可能なツールが30〜50個を超えると、Claudeの選択精度は劣化する」と明言しています。

この2つの問題は原因が違います。コンテキスト消費は「入力トークンが増える」という量の問題で、選択精度の劣化は「候補が多すぎて正しく選べなくなる」という質の問題です。MCPサーバーを何個も繋いで数百のツールを一度に並べる構成は、この2つの問題を同時に踏み抜きます。

厄介なのは、この2つが独立して悪化する点です。トークン消費だけを気にして小さなツールを大量に追加すれば、コンテキストの圧迫は軽くても選択精度の閾値は超えてしまいます。逆に少数の大きなツールをいくつか繋いだだけなら、トークン消費だけが膨らむ場合もあります。どちらか一方の指標だけを見ていると、もう一方の劣化を見逃します。

公式ドキュメントは、次のいずれかに当てはまるならTool Searchの導入を検討する目安だとしています。

MCPサーバーを2つ、3つと足していくうちに、この左側の条件に自然と当てはまっていきます。

ツール構成の変更はプロンプトキャッシュにも影響する

MCPサーバーを増やしたときの負担は、初期消費トークンの多さだけにとどまりません。Claude Codeはリクエストのたびに会話履歴を送っており、通常はプロンプトキャッシュによって同じ内容を安いキャッシュ読み取り単価で再処理できます。公式ドキュメントは、キャッシュがヒットしなかった原因を推定できたとき「likely cause: tool definitions changed」のように名指しする挙動があると明記しています。つまり、ツール定義が変わったことがキャッシュミスの原因として表示される仕組みが存在します。

ただし、Claude Codeでは後述のとおりTool Searchが既定で有効で、ツール定義自体は遅延ロードされます。この条件下でMCPサーバーの増減がキャッシュの接頭辞をどこまで、どの頻度で変えるかは公式ドキュメントに記載がありません。

Tool Searchはこの2つの問題をどう解決するか

Tool Search(Tool Search Tool)は、すべてのツール定義を最初から渡すのではなく、ツール名とサーバーの説明文だけをセッション開始時にロードし、Claudeが必要になったタイミングで検索して定義を取りに行く仕組みです。実装としては、ツール一覧の中でTool Search Tool自身だけを即時ロードし、それ以外のツールにはdefer_loading: trueを付けて遅延対象にします。Claudeが必要なツールを検索すると、APIはヒットしたツールをtool_referenceとして返し、それを完全なツール定義へ自動展開してからClaudeに渡します。

検索方式には2種類あります。tool_search_tool_regex_20251119はClaudeが正規表現パターンを組み立てて探すregex版、tool_search_tool_bm25_20251119は自然言語のクエリで探すBM25版です。検索1回につき既定で最大5件のツールが返り、Claudeが検索入力のlimitで1〜10,000件の範囲で件数を変えられます。1リクエストあたりdefer_loading: trueを付けられるツールの上限は10,000個で、Claude Fable 5.1・Opus 5・Sonnet 4.5以降など、tool_referenceブロックに対応したモデルでのみ利用できます。

効果も具体的な数字で示されています。公式ドキュメントによれば、Tool Searchは前述の約55,000トークンという初期消費を85%以上削減し、実際にロードされるのはそのリクエストで必要な3〜5個のツールだけになります。候補を絞り込んでから提示する仕組みなので、母集団のツール数が数千に増えても、Claudeが見るのは検索でヒットした少数のツールだけです。

Claude Codeでは、MCPツールのTool Searchが既定で有効になっています。ANTHROPIC_BASE_URLが自社以外のホストを指す場合、AzureホストのFoundry利用時、4.5世代より前のAgent Platformモデル利用時、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS指定時は、Tool Searchが自動で無効になり全ツールが起動時に読み込まれます。それ以外の既定構成では、ツール名とサーバーの説明文だけがセッション開始時にロードされ、MCPサーバーを追加してもコンテキストウィンドウへの影響は最小限に留まるとされ、サーバーごとの固定ツール数上限も設けていません(実質的な上限はコンテキストウィンドウの残量そのものになります)。一方、生のMessages API経由でMCPコネクタを使う場合は、ツールごとのdefer_loadingは既定でfalse(即時ロード)であり、Tool Searchで絞り込みたいツールには明示的にdefer_loading: trueを指定する必要があります。同じ仕組みでも、Claude Codeでは既定で有効、API直接利用では既定で無効という違いがあります。

サーバー側の説明文の書き方も検索精度を左右する

Tool Searchが機能するかどうかは、検索アルゴリズムだけでなく、検索対象になるMCPサーバー自身の説明文の質にも左右されます。公式ドキュメントは、MCPサーバーを実装する側に向けて「サーバーの説明文(server instructions)は、Skillsの説明文と同じように、Claudeがいつそのサーバーのツールを検索すべきかを判断する材料になる」としています。どんな種類のタスクをそのサーバーが扱うのか、どんな場面で検索すべきか、主要な機能は何かを説明文に書いておくことで、Claudeは数百あるMCPサーバーの中から検索すべきサーバーを絞り込めます。

説明文の質が検索精度を左右する一方で、ツール候補の絶対数が閾値を超えたときの選択精度の劣化(前段で触れた30〜50個の壁)は、説明文の書き方では解消しません。両者は別の軸の問題です。

MCPサーバーの設定とツール定義の圧縮の役割分担

Claude Codeで実際に/contextを確認したり、ENABLE_TOOL_SEARCHやalwaysLoadを設定してこの消費を抑える具体的な手順は、MCPのトークンオーバーヘッドを抑える設定にまとめています。説明文の2KB切り詰めなど実装上の制約も同記事で扱っているため、設定を変えたい場合はそちらを参照してください。CIやバックグラウンドセッションのように、読み込むサーバー自体を絞りたい場合は--mcp-configと--strict-mcp-configを使う方法もあります。2つのフラグの使い分けはClaude Codeの--mcp-configと--strict-mcp-configの使い分けで扱っています。

regex版とBM25版でクエリの書き方がどう変わるかはTool Search Toolのregex版とBM25版の違いを、ENABLE_TOOL_SEARCHの詳しい値ごとの挙動はAgent SDK Tool Searchの使い方を参照してください。

すべてのツールをTool Search任せにできるわけではない

Tool Searchは万能ではありません。先の早見表のとおり、ツールが10個未満で全部が毎回のリクエストで使われる、あるいはツール定義の合計が100トークン未満しかないような小規模な構成では、標準のツール呼び出しのほうが向きます。検索という1ステップが余計に挟まるぶん、母数が小さいうちはむしろ遠回りになります。

API側の推奨とClaude Codeの設定は別物です。API docsは、頻繁に使う3〜5個のツールをdefer_loadingの対象から外し、非遅延(non-deferred)にしておくことを推奨しています。毎ターン必ず使うツールまで遅延ロードにすると、そのぶん検索の往復が毎回発生し、レイテンシーだけが増えるためです。一方Claude Codeでは、MCPサーバー単位の設定としてalwaysLoadがあり、指定したサーバーのツールを丸ごと常時ロードにできます。ツール単位で常時ロードにしたい場合は、サーバー側の_metaにanthropic/alwaysLoadを設定します。API docsの「3〜5個を非遅延に」という推奨とClaude CodeのalwaysLoadは、単位(ツール単位かサーバー単位か)も設定方法も異なるので混同しないよう注意が必要です。

もう1つ見落としやすいのが、MCPサーバーを増やさずに済ませるという選択肢そのものです。Claude Codeのコスト削減ガイドは「gh・aws・gcloud・sentry-cliのようなCLIツールは、ツールごとの一覧をコンテキストに追加しないぶん、MCPサーバーより効率的」だとしています。Tool SearchはMCPサーバーを増やしたときの被害を抑える仕組みであって、CLIで済むタスクをわざわざMCPサーバー経由にする理由にはなりません。

まとめ

MCPサーバーを増やすことは、ツール定義という形でコンテキストを消費するコストと、候補が増えることで選択精度が下がるコストの、性質の違う2つの負債を同時に抱え込む行為です。Tool Searchは検索と遅延ロードによってこの両方を軽減しますが、頻用ツールまで遅延ロードにしない、サーバーの説明文を検索に見つけてもらえる粒度で書く、そもそもCLIで済むならMCPサーバーを増やさない、といった判断は依然として人間が設計する部分として残ります。Claude Codeでの具体的な設定方法はMCPのトークンオーバーヘッドを抑える設定を参照してください。