Claude Code MCP Tool Searchで実現するMCPツールの遅延読み込み — コンテキスト消費を最大95%削減する実践ガイド

MCP Serverを5つ、10と追加していくうちに、Claude Codeの応答が遅くなった——そんな経験はないだろうか。原因はツール定義によるコンテキストウィンドウの圧迫だ。GitHub、Slack、Sentry、Grafana、Splunkといった典型的なマルチサーバー構成では、ツール定義だけで約55,000トークンが消費される。50を超えるMCPツールを登録すると、その数値は77,000トークンにまで膨れ上がり、コード理解や推論に使える領域が大幅に削られる。

2026年1月にリリースされたMCP Tool Search（遅延読み込み）は、この問題を根本から解決する。本記事では、Tool Searchの内部メカニズムを技術的に解剖し、実測データに基づくコンテキスト削減効果と、実運用でのベストプラクティスまでを網羅的に解説する。

なぜMCPツールがコンテキストウィンドウを圧迫するのか

ツール定義のトークンコスト構造

MCPツール定義は、システムプロンプトの一部としてモデルに渡される。ツール名、説明文、引数名、引数のスキーマ——これらすべてがトークンとして計上される。1つのツールあたり数百〜数千トークンを消費するため、サーバーが増えるほどコストは線形に増加していく。

以下のような構成を想像してほしい。

{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" },
    "sentry": { "type": "http", "url": "https://mcp.sentry.dev/mcp" },
    "slack": { "type": "http", "url": "https://mcp.slack.com/mcp" },
    "notion": { "type": "http", "url": "https://mcp.notion.com/mcp" },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://..."]
    }
  }
}

5サーバー・50以上のツール構成で、Claude Code内で /cost を実行すると、会話開始直後にもかかわらず数万トークンが消費されていることが確認できる。

ツール数増加がもたらす2つの問題

問題はトークン消費だけではない。Anthropicの公式計測によると、利用可能なツールが30〜50を超えると、モデルのツール選択精度が顕著に低下する。ツール定義が多すぎると、モデルは「どのツールを使うべきか」の判断に迷い、誤ったツールを選択する頻度が増える。

トークン消費と精度低下のダブルパンチにより、MCPサーバーを増やすほどパフォーマンスが悪化するというジレンマが生まれていた。

Tool Searchの内部メカニズムを解剖する

自動判定の仕組み：コンテキストの10%閾値とdefer_loading

Claude CodeのTool Searchは、ツールの「個数」ではなく「トークン消費量」で発動を判定する。デフォルトでは、MCPツール定義がコンテキストウィンドウの10%を超えると自動的に有効化される。

有効化されると、各MCPツールに defer_loading: true が設定される。このフラグが付いたツールは、フル定義（名前・説明文・引数スキーマ）の代わりに、ツール名のみがシステムプロンプト末尾にリスト表示される。これにより、ツール1つあたりのコストが数百トークンから数トークンにまで圧縮される。

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}

3つのクエリモード

Claudeがツールを必要としたとき、ToolSearch経由でオンデマンドに検索・読み込みを行う。クエリモードは3つある。

キーワード検索 — 自然言語やキーワードで検索し、関連度順に最大5件が返される。

ToolSearch("slack message")
→ mcp__slack__send_message, mcp__slack__read_channel, ...

select: 直接選択 — 正確なツール名がわかっている場合、1件を直接ロードする。

ToolSearch("select:mcp__github__create_pull_request")
→ mcp__github__create_pull_request

+ 必須マッチ — プレフィックスにサービス名を必須指定し、残りのキーワードでランキングする。

ToolSearch("+slack send")
→ slackのツールのみから、sendに関連するものを返す

正直、最初はキーワード検索だけで十分だと思っていたが、MCPサーバーが10個を超えてくると + 必須マッチのありがたみが身に染みる。

API層のアーキテクチャ

API層では、2つの検索バリアントが存在する。

• Regex（tool_search_tool_regex_20251119）: Claudeがre.search()構文のRegexパターンを構築して検索する
• BM25（tool_search_tool_bm25_20251119）: 自然言語クエリでBM25ランキングにより検索する

いずれのバリアントも、ツール名・説明文・引数名・引数説明の全フィールドが検索対象となる。

一度展開されたツールは会話履歴に tool_reference ブロックとして残り、以降のターンでは再検索不要だ。セッション内キャッシュとして機能するため、同じツールを何度も検索するオーバーヘッドは発生しない。

実測データで見るコンテキスト削減効果

Before/After：50+ツール構成での比較

実測データを見てみよう。

Tool Search自体のオーバーヘッドは約500トークン程度に過ぎない。削減されたトークン分がコード理解や推論に回せるため、体感的な応答品質も向上する。

ツール選択精度の改善

コンテキスト節約だけではない。Anthropicの公式ベンチマークでは、Tool Searchを有効にすることでモデルに提示されるツール数が絞られ、選択精度も向上することが報告されている。大量のツールから「正しい1つ」を選ぶ必要がなくなり、検索で絞り込まれた3〜5件から選択するため、精度が構造的に改善される仕組みだ。

確認手順は簡単で、以下のように環境変数を切り替えて /cost で比較すればよい。

# Tool Search無効で起動
ENABLE_TOOL_SEARCH=false claude

# Tool Search有効で起動（デフォルト）
ENABLE_TOOL_SEARCH=true claude

最適な設定戦略：環境別コンフィグガイド

ENABLETOOLSEARCHの4つのモード

settings.jsonでの永続化

~/.claude/settings.json の env フィールドで永続設定できる。

小規模構成（MCPサーバー3〜5個）

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto"
  }
}

autoのデフォルト閾値（10%）で十分機能する。ツール数が少なければそもそも発動しないため、オーバーヘッドもゼロだ。

中規模構成（MCPサーバー5〜10個）

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5"
  }
}

閾値を5%に下げることで、より早い段階でTool Searchが発動する。

大規模構成（MCPサーバー10個以上）

{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

10個以上のサーバーを運用する環境では true 固定を推奨する。理由は次のセクションで述べるが、auto:N にはタイミングに関する既知の問題がある。

対応モデルの制限

Tool Searchは tool_reference ブロックをサポートするモデルでのみ動作する。具体的には Sonnet 4以降、Opus 4以降 が対応しており、Haikuは非対応 だ。

実運用のベストプラクティスとハマりポイント

ツール命名・説明文の設計がTool Search精度を左右する

Tool Searchは、ツール名と説明文を検索対象とする。つまり、命名と説明文の品質が検索精度に直結する。

良い例：

{
  "name": "github_create_pull_request",
  "description": "Create a new pull request on GitHub with specified title, body, base branch, and head branch"
}

悪い例：

{
  "name": "create_pr",
  "description": "Creates a PR"
}

ポイントは3つ。

1. 一貫したプレフィックスを付ける（github_, slack_, jira_）。+ 必須マッチが効果的に機能する
2. 説明文にセマンティックなキーワードを豊富に含める。BM25検索の精度が向上する
3. 引数名も検索対象であることを意識する。q ではなく search_query のように意味のある名前にする

頻用ツールのdefer_loading除外戦略

API層では、特定のツールを defer_loading: false に設定して即時利用可能にできる。毎リクエストで確実に使うツール3〜5個は、遅延読み込みから除外しておくのが最適だ。

{
  "type": "mcp_toolset",
  "mcp_server_name": "database-server",
  "default_config": {
    "defer_loading": true
  },
  "configs": {
    "search_events": {
      "defer_loading": false
    }
  }
}

default_config で全ツールを遅延読み込みにしつつ、configs で個別に除外する。このパターンは覚えておいて損はない。

知っておくべき制限事項と既知のバグ

主要な制限：

• 最大ツール数: 10,000
• 1回の検索結果: 3〜5件
• Regexパターン長: 最大200文字
• Tool Use ExamplesとTool Searchは併用不可。ツール使用例を提供する必要がある場合は、Tool Searchを無効にするしかない

auto:Nのタイミングバグ（GitHub Issue #19422）：

auto:N モードでは、MCPサーバーの接続完了前にツールサイズの計測が行われるケースが報告されている。計測タイミングでツール定義が0バイトと判定され、閾値を下回ると見なされてTool Searchが発動しない。180以上のMCPツールを持つ環境で全ツールがコンテキストに読み込まれてしまう事例が確認されている。

多数のサーバーを運用する環境では、auto:N ではなく ENABLE_TOOL_SEARCH=true で強制有効化するのが安全だ。

よくあるアンチパターン：

キーワード検索で見つかったツールを、さらに select: で再検索する必要はない。キーワード検索の時点でツールはすでにロード済みだ。

# アンチパターン（冗長）
ToolSearch("slack")        → mcp__slack__read_channel が見つかる
ToolSearch("select:mcp__slack__read_channel")  → 不要！

# 正しい使い方
ToolSearch("slack")        → そのまま使える

まとめ：MCPエコシステムのスケールに備える

MCP Tool Searchは「MCPツールが増えるほど性能が落ちる」という問題への根本的な解答だ。50以上のツール定義で77,000トークンを消費していた環境が、わずか8,700トークンに圧縮される。しかもツール選択精度まで向上するという、コストと品質の両方を改善する機能である。

設定は1行で完了する。

ENABLE_TOOL_SEARCH=true claude

MCPサーバーを3つ以上使っているなら、今すぐ有効化しない理由はない。ツール命名や説明文の設計を意識することで、Tool Searchの効果はさらに高まる。MCP Server開発者にとっても、ツールの発見性（discoverability）は今後ますます重要なポイントになるだろう。

MCPツールが100を超える時代に備え、遅延読み込みを標準プラクティスとして組み込んでおこう。