MCP サーバーを増やしてもコンテキストを食わせない — Claude Code の Tool Search でトークン消費を95%削減

@djrio_vr 氏のポストが、Claude Code の MCP Tool Search 機能を紹介し、大きな反響を呼んでいます（いいね 418、ブックマーク 522）。

Claude Codeで登録してるMCPサーバが増えてくるとコンテキストがかなり食われてたけど、Tool Searchという必要な時だけ動的ロードするオプションをONにしたらめちゃくちゃコンテキスト節約になった！
環境変数 ENABLE_TOOL_SEARCH=true と設定するだけ

MCP サーバーを複数接続していると、会話を始める前からコンテキストウィンドウの大部分が消費されてしまう問題は、多くの Claude Code ユーザーが直面していました。本記事では、この問題の構造と Tool Search による解決策を技術的に解説します。

MCP ツール定義がコンテキストを圧迫する構造

なぜ MCP サーバーを増やすとコンテキストが減るのか

Claude Code に MCP サーバーを接続すると、各サーバーが提供する全てのツール定義がコンテキストウィンドウに読み込まれます。ツール定義には、ツール名、説明文、JSON スキーマ（パラメータの型・制約・説明）が含まれており、1つのツールだけでも数百トークンを消費します。

[MCP サーバー接続時のコンテキスト構造]

システムプロンプト          ～数千トークン
├── Claude Code の指示
├── CLAUDE.md の内容
└── ユーザー設定

ツール定義                 ★ ここが問題
├── 組み込みツール（Read, Edit, Bash 等）
├── MCP サーバー A のツール × 10個
├── MCP サーバー B のツール × 15個
├── MCP サーバー C のツール × 20個
└── ...

会話履歴                   ← 残りがここに使われる
├── ユーザーのメッセージ
└── Claude の応答

具体的な数値

GitHub Issue #3036 では、約20個の MCP サーバーを接続した環境で、開始時点からコンテキスト使用率が8〜18%に達し、わずか5プロンプトで100%に到達する現象が報告されています。

コミュニティの検証によると、以下のような消費が発生します。

MCP ツール数	初期トークン消費	200K ウィンドウに占める割合
10ツール程度	約10K〜15Kトークン	5〜8%
30ツール程度	約30K〜40Kトークン	15〜20%
50ツール以上	約77Kトークン	38%

50以上のツールを接続すると、会話を始める前にコンテキストの4割近くが消費される計算です。Sonnet の 200K トークンウィンドウでこの状態なので、実質的な作業領域は大幅に制限されます。

問題の影響

コンテキストの圧迫は、単にセッションが短くなるだけでなく、複数の悪影響を及ぼします。

影響	説明
セッション寿命の短縮	会話の蓄積が早く限界に達し、頻繁にリセットが必要になる
指示追従性の低下	コンテキストが圧迫されると、CLAUDE.md やシステムプロンプトの指示を見落としやすくなる
コスト増加	毎回のリクエストに全ツール定義が含まれるため、API コストが膨らむ
ツール選択精度の低下	選択肢が多すぎると、適切なツールを選べない場合がある

Tool Search の仕組み

遅延ロードによる解決

Tool Search は、全ツール定義を事前ロードする代わりに、必要なときに必要なツールだけを動的にロードする仕組みです。2026年1月に Claude Code v2.1.7 で導入されました。

[従来: 全ツール事前ロード]
セッション開始 → 全50ツールの定義をロード（77Kトークン消費）
              → 実際に使うのは3〜5ツール
              → 残り45ツールの定義は無駄

[Tool Search: オンデマンドロード]
セッション開始 → 検索インデックスのみロード（約8.7Kトークン）
タスク実行時   → MCPSearch ツールで必要なツールを検索
              → マッチした3〜5ツールだけロード（約3Kトークン）
              → 使わないツールはロードしない

動作の流れ

Tool Search は以下の5ステップで動作します。

検出: MCP ツールの定義がコンテキストウィンドウの10%を超えるかチェック
遅延マーク: 閾値を超えたツールに defer_loading: true を設定
検索ツール挿入: 全定義の代わりに MCPSearch ツールをコンテキストに挿入
オンデマンド検索: Claude がタスクに必要なツールをキーワードで検索
選択的ロード: クエリごとに関連する3〜5個のツールだけをロード

検索には2つのモードがあります。

モード	方法	用途
Regex モード	正確なパターンマッチ（例: `"weather"`）	ツール名が分かっている場合
BM25 モード	自然言語によるセマンティック検索	「天気を調べたい」のような曖昧なクエリ

効果の数値

指標	従来	Tool Search	改善率
初期トークン消費（50+ツール）	約77K	約8.7K	89%削減
コンテキスト保持率	62%	95%以上	—
ツール選択精度（Opus 4）	49%	74%	+25pt
ツール選択精度（Opus 4.5）	79.5%	88.1%	+8.6pt

トークン消費の削減だけでなく、ツール選択の精度も向上する点が重要です。選択肢が少ない方が、モデルは適切なツールを選びやすくなります。

設定方法

基本: デフォルトで有効

Tool Search は現在のバージョンではデフォルトで有効です。MCP ツール定義がコンテキストの10%を超えると自動的にアクティベートされます。つまり、ツールが少なければ従来通り全ロード、多ければ自動で Tool Search に切り替わるという挙動です。

ツイートで紹介されている ENABLE_TOOL_SEARCH=true は「常時有効」の設定で、ツール数に関係なく Tool Search を強制的にオンにします。

環境変数による制御

ENABLE_TOOL_SEARCH 環境変数で動作を制御できます。

値	動作
`auto`（デフォルト）	MCP ツールがコンテキストの10%を超えたら有効化
`auto:<N>`	カスタム閾値。例: `auto:5` で5%超過時に有効化
`true`	常時有効
`false`	無効（全ツールを事前ロード）

1
2
3
4
5
6
7
8
# カスタム閾値（5%）で起動
$ ENABLE_TOOL_SEARCH=auto:5 claude

# 常時有効で起動
$ ENABLE_TOOL_SEARCH=true claude

# 無効化して起動
$ ENABLE_TOOL_SEARCH=false claude

settings.json での設定

環境変数を毎回指定する代わりに、settings.json の env フィールドに設定できます。

1
2
3
4
5
{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Tool Search の無効化

特定のケースで Tool Search を無効にしたい場合は、disallowedTools で MCPSearch ツールをブロックできます。

1
2
3
4
5
{
  "permissions": {
    "deny": ["MCPSearch"]
  }
}

確認方法

/context コマンド

Claude Code 内で /context を実行すると、現在のトークン使用状況を確認できます。Tool Search が有効な場合、MCP ツール定義によるトークン消費が大幅に減少しているはずです。

/doctor コマンド

/doctor を実行すると、MCP サーバーごとの詳細なブレークダウンが表示されます。どのサーバーがどれだけトークンを消費しているかを特定できます。

Tool Search が効果的なケースと不要なケース

効果が大きいケース

MCP サーバーを5つ以上接続している場合
合計ツール数が20以上ある場合
1セッションで使うツールが全体の一部の場合（大半のケース）

効果が限定的なケース

MCP サーバーが1〜2個で、ツール定義が小さい場合
全てのツールを毎セッション使う場合（検索オーバーヘッドが増える）
ツール定義が既にコンパクトな場合

MCP サーバー開発者向けの注意点

Tool Search が有効な環境では、ツールの発見されやすさが重要になります。

ツール名の設計

# 良い例（検索で見つかりやすい）
github_create_issue
slack_send_message
postgres_query

# 悪い例（検索で見つかりにくい）
create
send
query

ツール説明の充実

ツール説明にキーワードを豊富に含めることで、BM25 モードでの検索精度が向上します。

1
2
3
4
{
  "name": "github_create_issue",
  "description": "Create a new GitHub issue in a repository. Use this to report bugs, request features, or track tasks. Supports labels, assignees, and milestone assignment."
}

サーバー説明（instructions）の活用

MCP サーバーの instructions フィールドは、Tool Search 環境で特に重要です。Claude がどのような場面でそのサーバーのツールを検索すべきかを記述します。

Tool Search 以外のコンテキスト最適化

Tool Search はツール定義の問題を解決しますが、MCP のコンテキスト消費にはツール出力の問題もあります。

ツール出力のトークン消費

ツール出力の例	トークン消費
Playwright のスナップショット	約56KB
GitHub Issues 20件の取得	約59KB
アクセスログ1件	約45KB

MAX_MCP_OUTPUT_TOKENS の設定

Claude Code はデフォルトで MCP ツール出力が 25,000 トークンを超えるとブロックし、10,000 トークンで警告を表示します。

1
2
# 大きな出力を許可する場合
$ MAX_MCP_OUTPUT_TOKENS=50000 claude

サードパーティの補完ツール

Tool Search がツール定義の問題を解決するのに対し、MCP Context Mode のようなサードパーティツールはツール出力の問題に対処します。315KB の生出力を 5.4KB に圧縮する事例が報告されています。

まとめ

問題の本質: MCP ツール定義が全てコンテキストに事前ロードされ、50+ツールで約77Kトークン（ウィンドウの38%）を消費する
Tool Search の解決策: 必要なツールだけをオンデマンドでロードし、初期消費を約8.7Kトークン（95%削減）に抑える
デフォルトで自動有効: コンテキストの10%を超えると自動的にアクティベートされる。手動で ENABLE_TOOL_SEARCH=true を設定すれば常時有効にできる
精度も向上: トークン削減だけでなく、ツール選択の精度も Opus 4 で49%→74%に向上する
設定は簡単: 環境変数1つまたは settings.json の1行で有効化できる
開発者も対応が必要: ツール名と説明を検索しやすく設計することで、Tool Search 環境での発見性が向上する

MCP サーバーを増やしてもコンテキストを食わせない — Claude Code の Tool Search でトークン消費を95%削減#

MCP ツール定義がコンテキストを圧迫する構造#

なぜ MCP サーバーを増やすとコンテキストが減るのか#

具体的な数値#

問題の影響#

Tool Search の仕組み#

遅延ロードによる解決#

動作の流れ#

効果の数値#

設定方法#

基本: デフォルトで有効#

環境変数による制御#

settings.json での設定#

Tool Search の無効化#

確認方法#

/context コマンド#

/doctor コマンド#

Tool Search が効果的なケースと不要なケース#

効果が大きいケース#

効果が限定的なケース#

MCP サーバー開発者向けの注意点#

ツール名の設計#

ツール説明の充実#

サーバー説明（instructions）の活用#

Tool Search 以外のコンテキスト最適化#

ツール出力のトークン消費#

MAX_MCP_OUTPUT_TOKENS の設定#

サードパーティの補完ツール#

まとめ#

参考#