Claude Codeのツール検索：エージェントが必要なMCPツールを見つける方法

Claude Codeに複数のMCPサーバーを接続している場合、ツール検索を使うと、すべての定義をあらかじめ読み込むことなく、必要なツールを必要に応じて読み込めます。起動時にエージェントが受け取るのは、遅延読み込みされるツールの名前とサーバーの指示であり、その後、必要なものをカタログから検索します。これにより、多数のツールを扱いやすくなります。Anthropicのドキュメントによると、一度に読み込むツールが30〜50個を超えると、選択精度が低下します。これは一般的な指針であり、あなたのセッションで測定した値ではありません。ツール検索は、モデルが対応していればデフォルトで有効ですが、プラットフォーム、プロキシ、または設定によって無効になることがあります。

Ailootのドキュメント：API、キー、セットアップ。

ツール検索を使わない場合のコンテキスト#

接続されているMCPサーバーごとに、エージェントが呼び出せるツールの一覧にツールが追加されます。ツール検索を使わない場合、その定義（名前、説明、パラメータースキーマ）はあらかじめコンテキストに読み込まれます。セッション開始時には、サーバーがバックグラウンドで接続します。接続が完了していないサーバーのツールが必要になると、Claude Codeは内部のWaitForMcpServersツールを使って待機します。サーバーごとに、接続によって追加されるツール数とトークン数を個別に確認できます。

Anthropicの公式ドキュメントには、概算値が2つ示されています（一般的な数値で、測定方法は明記されていません）。

• 50個のツールは、コンテキストトークンを1万〜2万消費することがある。
• 一度に読み込むツールが30〜50個を超えると、適切なツールを選ぶ精度が低下する。

設定からツール検索の状態を確認する#

現在のセッションでツール検索が機能するかどうかを確認するには、次の条件をチェックします。

• 応答に使われているモデル — Sonnet/Haiku/Opus 4.5以降ならこの機能を利用できます。それ以前のモデルでは利用できません。
• ANTHROPIC_BASE_URLが標準以外のホストに設定されているか — その場合、ENABLE_TOOL_SEARCHで明示的に有効にしない限り、この機能はデフォルトでオフになります。
• ENABLE_TOOL_SEARCH変数の値 — falseはこの機能を完全に無効にします。auto/auto:Nは、定義の総量がしきい値に達した場合にのみ有効にします。
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASが設定されているか — 組織のマネージド設定がない場合、ユーザーがENABLE_TOOL_SEARCHを設定していても、ツール検索はオフのままです。
• 設定のpermissions.denyでToolSearchツールがブロックされているか — この制限があると検索は無効になります。
• 使用しているプラットフォーム — Azure上のMicrosoft Foundryデプロイではこの機能を利用できません。Google Cloud Agent Platformでは、動作がClaude Codeのバージョンとモデルによって異なります。

この確認で設定上の状態は判断できますが、セッション内で実際に観察することはできません。Agent SDKドキュメントのMCPセクションとツール検索セクションには、インターフェース上で「ツール検索：オン/オフ」を直接示すインジケーターの記載はありません。この2つの文書に記載がないからといって、そのようなインジケーターがどこにも存在しないと証明されるわけではありません。

たとえば、セッションを開始する前にENABLE_TOOL_SEARCH=auto:15 claudeのように変数を設定できます。特定のサーバーのツールを常に読み込むには、そのサーバーの設定でalwaysLoad: trueフィールドを使います。これはすべてのサーバータイプで利用できます。条件と制限については、以下のalwaysLoadのセクションで説明します。

ツール検索の仕組み#

ツール検索が有効な場合、セッション開始時にコンテキストへ読み込まれるのは、遅延読み込みされるツールの名前とサーバーの指示だけです。サーバーの指示には、そのサーバーがどのようなタスクに役立つかが記載されています。まだコンテキストにない機能が必要なタスクでは、エージェントが自らカタログを検索して適切なツールを見つけます。

Agent SDKドキュメントでは、検索の仕組みをさらに詳しく説明しています。デフォルトでは、1回の検索でカタログから関連性の高いツールを最大5個読み込みます。エージェントがツールを見つけたメッセージがSDKによって圧縮されるまで、後続のターンでも利用できます。圧縮後は、以前に見つけたツールがコンテキストから外れることがあり、次に必要になったときにエージェントが再検索します。カタログは最大1万個のツールに対応しています。Claude Code自体のMCPドキュメントには、こうした具体的な数値は記載されていませんが、遅延読み込みの同じ原則が説明されています。

Agent SDKドキュメントによると、検索を行うたびに追加のラウンドトリップが1回発生します。そのラウンドトリップに何が正確に含まれるかは、ドキュメントに明記されていません。Claude Codeについては、MCPドキュメントでエラー報告の違いも説明されています。ツール検索を使わない場合、Claude Codeはサーバーへの接続失敗をモデルに伝えません。検索が有効な場合、どのサーバーへの接続に失敗したかとエラー内容がモデルに伝えられます。

Claude Codeは、1つのサーバーから読み込むツール数に固定の上限を設けていません。実際の上限は、該当セッションのコンテキストウィンドウの予算です。

ツールの設定は、AIエージェントのコンテキスト管理に含まれる作業の1つです。

ツール検索がデフォルトで無効になる場合#

この機能はデフォルトで有効ですが、動作するかどうかはモデル、APIホスト、プラットフォームによって異なります。

モデル。 ツール検索には、tool_referenceブロックに対応するモデルが必要です。Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.5、またはそれ以降のモデルが該当します。それ以前のモデルでは、Claude Codeはツールの定義をあらかじめ読み込みます。

APIホスト。 ANTHROPIC_BASE_URL変数がサードパーティのホストを指している場合、Claude Codeはツール検索を無効にします。ほとんどのプロキシは、特殊なtool_referenceブロックを中継しないためです。これは、Anthropicのアドレスへ直接接続する代わりに、独自のゲートウェイやプロキシサーバーを経由してClaudeに接続する場合に該当します。無効化の理由は標準以外のANTHROPIC_BASE_URLであり、サブスクリプションの支払い方法自体が原因ではありません。この動作はENABLE_TOOL_SEARCHを明示的に設定すれば上書きできます。プロキシ自体がtool_referenceブロックに対応していない場合、この機能を強制的に有効にするとリクエストエラーになります。この場合、定義の事前読み込みにはフォールバックしません。

デプロイプラットフォーム。 Azure上でホストされたMicrosoft Foundryのデプロイでは、ツール検索は機能しません。サーバーがリクエストを拒否し、ENABLE_TOOL_SEARCHで上書きすることもできません。Google Cloud Agent Platformでは、Claude Codeのバージョン2.1.221より前は、ENABLE_TOOL_SEARCH=trueを明示的に設定しない限り、すべてのモデルでこの機能がオフでした。このバージョン以降は、Opus/Sonnet/Haiku 4.5以降でデフォルトで有効になります。このプラットフォーム上のそれ以前のモデルでは、必要な内部ヘッダーをサーバーのインフラが拒否するため、Claude Codeは引き続きすべてのツールをあらかじめ読み込みます。

ENABLE_TOOL_SEARCH変数には、次の5つの設定があります。

• 未設定 — 上記の例外を除く標準の動作。
• true — 対応モデルでこの機能を有効にします。ただし、Azure Foundryと、それ以前のAgent Platformモデルの2つの場合を除きます。tool_referenceブロックに対応していないプロキシ経由で送信したリクエストは失敗します。
• auto — ツール定義の合計がコンテキストウィンドウの10%未満である間は、Claude Codeがツールをあらかじめ読み込み、そのしきい値に達すると遅延読み込みに切り替えます。
• auto:N — 同じ仕組みですが、しきい値の割合を手動で指定します。
• false — この機能を完全に無効にし、すべてのツールをあらかじめ読み込みます。

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS変数もあります。この変数が設定されていると、ツール検索はオフのままになり、ユーザーがENABLE_TOOL_SEARCHを設定しても変わりません。例外として、Claude Codeバージョン2.1.227以降では、組織がマネージド設定を通じてツール検索を有効にしている場合があります。

alwaysLoadの機能とコンテキストおよび起動への影響#

サーバーの設定にあるalwaysLoad: trueフィールドは、すべてのサーバータイプで利用できます。これを指定すると、ENABLE_TOOL_SEARCHの設定にかかわらず、そのサーバーのすべてのツールが起動時にコンテキストへ読み込まれます。エージェントは使用前にそれらを検索する必要がありません。

ツールを常に読み込むことには、2つの影響があります。あらかじめ読み込まれる各ツールが、タスク自体に使えるはずのコンテキストを一部消費します。また、セッションの起動時には、このサーバーへの接続が完了するまで、標準の5秒のタイムアウト内で待機します。

例外は、有効なキャッシュ項目があるリモートサーバーです。この場合、接続せずにキャッシュからツールを提供するため、起動は遅れません。機能の段階的なロールアウト中にアカウントですでに有効になっていた場合を除き、検出キャッシュはデフォルトでオフです。MCP_DISCOVERY_CACHE=1で明示的に有効にすることもできます。高速起動の例外が適用されるのは、キャッシュが有効で、有効な項目が含まれている場合です。エージェントが検索で作業する際にそのツールを必要としていたかどうかにかかわらず、alwaysLoadを指定したツールは常にコンテキストを占有します。

独自のMCPサーバーを作成する場合、サーバーの指示は、Skillsと同様に、ツールを検索するタイミングをClaudeが理解する助けになります。Claude Codeはデフォルトで、各ツールの説明と各サーバーの指示を2048文字までに切り詰めるため、重要な詳細は先頭に記載してください。

Claude Codeの拡張方法を選ぶ際は、接続しているMCPサーバーの数だけでなく、ほかの要素も考慮します。Claude Codeで一度に保持する拡張機能の数とClaude Codeで何を選ぶか：Skills、Subagents、MCP、Pluginsのガイドでは、タスクごとにSkills、Subagents、MCP、Pluginsを検討しています。特定のMCPサーバーを手順に沿って設定する方法については、Claude Code向けMCPサーバー：すぐに使える組み合わせを参照してください。

次にすること#

定義を無理なくコンテキストに収められる、およそ10個未満のツールセットであれば、Agent SDKドキュメントによると、通常は一度にすべて読み込むほうが高速です。ただし、Claude Codeのデフォルトの動作では、変数が未設定で、上記の制限に該当しない場合、ツール検索が有効になり、alwaysLoadを指定したサーバーを除き、検索するまでMCPツールの読み込みは遅延されます。

この場合、ENABLE_TOOL_SEARCH=autoを明示的に設定できます。定義の合計がコンテキストウィンドウの10%未満である間はあらかじめ読み込まれ、しきい値に達すると検索が有効になります。ツールセットが増えないとわかっている場合は、ENABLE_TOOL_SEARCH=falseにする方法もあります。その場合、上記のとおり、Claude Codeはサーバーへの接続失敗をモデルに伝えなくなります。

それ以外の場合は、環境が変わったときに動作条件を改めて確認します。

• セッションでそれ以前のモデルを使っている場合は、Sonnet/Haiku/Opus 4.5以降に切り替える。
• 標準以外のANTHROPIC_BASE_URLを使って接続している場合は、プロキシ自体がtool_referenceブロックを中継するときに限り、ENABLE_TOOL_SEARCH=trueを明示的に設定する。
• デプロイプラットフォームが例外の対象に含まれていないことを確認する。例外はAzure Foundryと、それ以前のGoogle Cloud Agent Platformモデルです。

条件を満たし、設定で検索がブロックされていなければ、必要なMCPサーバーを接続できます。alwaysLoadを使うのは、そのセッションのすべてのターンでツールが必要なサーバーに限り、それ以外は検索による読み込みに任せます。

Ailootを通じてAIモデルを利用したい場合は、Ailootをご覧ください。