Tips & Tricks · Parhum Khoshbakht

MCP Tool Search: 12 万トークンのツールスキーマを遅延読み込みにした方法

作業開始前に、24 個の MCP コネクタがコンテキストウィンドウの約 60% を消費していました。Tool Search を有効にしたところ、〜3K トークンに低下。before/after の /context 出力と、効果のあった統合パターンを紹介します。

何週間も気づかなかった隠れたコスト

Claude Code に MCP (Model Context Protocol) サーバーをインストールすると、ツールが手に入ります。たくさんのツールです。GitHub MCP サーバーだけで 35 個。issue、プルリクエスト、ブランチ、コメント、リリース、ワークフロー実行、デプロイ、セキュリティアラートなどのためのものです。

デフォルトで合わせて手に入るのが、セッション開始時にコンテキストへ注入される、すべてのツールの完全な JSON スキーマです。名前、説明、パラメータの型、列挙値、例 — そのすべてが、プロンプトを 1 つも入力する前に注入されます。

Statnive の構築過程で、24 個の MCP サーバーを接続しました。セッションが窮屈に感じ始めるまで、コストについて考えませんでした。それから初めて /context を実行しました。

本記事は、ビフォーアフター、85% の仕事をした 1 つのフラグ、そして仕事を仕上げた他の 3 つのパターンの話です。

/context が私たちに見せたもの

最適化前の /context 出力の関連部分は次のとおりです。

MCP サーバーツール数消費トークン
GitHub35〜26,000
Slack11〜21,000
Jira〜20〜17,000
Playwright (ブラウザ自動化)21〜13,647
Context7 (ライブラリドキュメント)〜15〜8,000
その他 19 のコネクタ〜190〜50,000
MCP オーバーヘッド合計〜290〜135,000

これは概ね、200K のコンテキストウィンドウ全体の 67% が、そのセッションで使わないかもしれないツールの定義に費やされていたということです。研究者が他で文書化したパターンが当てはまります。MCP ツールあたりの平均オーバーヘッドは 〜500〜710 トークンで、適度なコネクタ負荷 (24 サーバー) は作業開始前に 48,000〜120,000 トークンを消費するのが日常茶飯事です。最も極端な事例は Docker の MCP サーバーで、135 個のツールで単独で 〜126,000 トークンです。

実作業の会話、システムプロンプト、組み込みツール、CLAUDE.md、スキルメタデータ、自動コンパクトバッファのために残っていたのは 〜65K トークンでした。だからすべてが窮屈に感じたのです。

Tool Search: 85% の仕事をした 1 つのフラグ

Claude Code v2.1.7 が MCP Tool Search を出荷しました。起動時にすべてのツールスキーマを注入する代わりに、Tool Search はツール名と説明の軽量な 〜5K トークンのインデックスを構築します。個別のツールの完全なスキーマは、Claude が実際にそれを呼び出す決断をしたときにだけ読み込まれます。一度読み込まれると、セッション中はキャッシュされます。

Anthropic の内部テストでは 134K から 〜5K トークンへ — 85% の削減を示しました。直感に反しますが、MCP 評価における精度は上がりました。Opus 4 は同じベンチマークで 49% から 74% に飛躍し、おそらくモデルが必要のないツールスキーマで溺れていなかったためです。

Tool Search はツールの説明がコンテキストウィンドウの約 10% (〜20K トークン) を超えると自動的に有効化されます。それ未満ではオフのままで、必要ないという仮定の下にあります。私たちは閾値をはるかに超えているので、常に有効です。

有効化後、/context は劇的に異なって見えました。

ソースBeforeAfter
MCP ツールスキーマ〜135,000〜3,000 (インデックスのみ)
MCP ツールスキーマ (4 ツール使用したセッション中)〜135,000〜6,500 (インデックス + 4 ツールスキーマ)
実作業に使えるコンテキスト〜65,000〜190,000

決して飛ばさない検証ステップ: セッション開始時に /context を実行し、ツールスキーマが遅延されているか、または Tool Search が有効になっている行を確認してください。そうでなければ、何もないものに対価を払っていることになります。

CRUD 爆発の統合

Tool Search が最大の単一レバーでしたが、個別のツールの説明が肥大化していたり、サーバーが似たり寄ったりのツールを多数公開していたりすると、これだけでは助けになりません。

私たちは内部 MCP サーバーの 1 つを、研究で文書化されている action-parameter consolidation というパターンを使って再構築しました。issue 管理のためのオリジナルの 10 ツール API:

create_issue, update_issue, delete_issue, list_issues, get_issue,
add_comment, update_comment, delete_comment, list_comments, get_comment

これが 1 つのツールになりました。

manage_issues({ action: "create" | "update" | "delete" | "list" | "get",
                target: "issue" | "comment", ... })

このパターンを適用した開発者の文書化された結果: 20 ツールが 14,214 トークンから 5,663 トークンに低下 — 60% の削減です。action パラメータが列挙されており、ツールの説明がサポートされるすべての操作を挙げているため、モデルは正しくルーティングします。私たち自身の統合でも同様の結果が得られました。概ね 9,800 トークンが 4,100 トークンになりました。

Tool Search がスキーマ読み込みを遅延させるとしても、1 つの太いツールのオンデマンド読み込みは、10 個の細いツールよりはるかに小さくなります。スキーマオーバーヘッドは繰り返しの定型コード (型定義、エラーエンベロープ、ページネーションパターン) で支配されるためです。

説明を積極的に削る

同じコインの反対側です。ツールの説明にあるマーケティング文は、本物のトークンを消費します。

次のような説明:

“Search the web using Tavily Search API. Best for factual queries requiring reliable sources and citations from authoritative web content. Handles complex topics with academic depth and provides comprehensive results with relevance scoring…”

これは 87 トークンかかります。同じルーティングシグナルを次のように:

“Search using Tavily. Best for factual/academic topics with citations.”

これは 12 トークンです。290 ツール全体で、説明 1 つあたり平均 50 トークンの節約は 〜14,500 トークンです。

私たちが使うルール: 説明は Claude がこのツールを呼ぶべきかどうかを決定するのを助けるべきで、ツールを宣伝すべきではありません。ルーティング判断を変えないものはすべて削ります。

ツールを Eager に保ったとき

ほぼすべてのセッションで発火するため、いくつかのツールは eager に読み込みたいものがあります。

  • Read、Write、Edit、Grep、Glob、Bash — 組み込みで MCP ではありませんが、原則は同じです。呼び出し頻度の高さが常時読み込みを正当化します。
  • セッションあたり何度も使う 2 つの MCP サーバー — 内部リリースツールとドキュメント取得サーバー。スキーマ合計は 〜3,500 トークンです。セッションあたり 6 回以上のオンデマンド読み込みは、再取得レイテンシで eager 読み込みの節約より高くつきます。

Tool Search はサーバーごとの eager 許可リストをまさにこの目的でサポートしています。外科的に使ってください。すべての eager ツールは恒久的なオーバーヘッドです。

出力を制限しないと、出力に制限される

MCP の環境変数 MAX_MCP_OUTPUT_TOKENS のデフォルトは ツールレスポンスあたり 25,000 トークンです。1 ターンに 1 ツール呼び出しで 200K ウィンドウなら寛大な値です。24 のコネクタと 1 ターンに複数の呼び出しに展開するツールでは、生の API レスポンスでコンテキストを埋める保証された方法です。

私たちは 4,000 にキャップし、最も出力の重いサーバーにはサーバーサイドのページネーションとサマリーファーストのレスポンス形状をサポートさせました。GitHub の list-issues 呼び出しは、200 件の issue をコンテキストにダンプする代わりに、最初の 20 件と has_more: true マーカー、継続トークンを返すようになりました。必要ならモデルがさらに尋ねられますが、通常はそうしません。

複雑なマルチツールワークフローには、Programmatic Tool Calling (Claude がオーケストレーションコードを書き、サンドボックス環境で実行され、最終結果のみがコンテキストに入る) が、Anthropic の内部テストにおける研究重視のタスクで 〜37% のトークン削減を示しました。私たちは 1 つのワークフロー — 6 つのドキュメントサーバーをヒットする Q&A エージェント — に使っており、節約は維持されています。

時々しか使わないツールには CLI > MCP

直感に反しますが本当です。まれに使うツールには、シェルコマンドの方が MCP サーバーよりも安価です。gh、aws、gcloud、sentry-cli、wp — これらは Bash ツール経由で実行され、永続的なコンテキストオーバーヘッドはゼロです。Bash ツールの説明 (既に読み込み済み) があなたが支払うコンテキストのすべてです。CLI バイナリのヘルプテキストは、Claude が読んだ場合にのみ読み込まれます。

私たちはまれにしか使われない 3 つの MCP サーバーを引き、CLI 利用に置き換えました。それだけで 〜12,000 トークンのベースラインオーバーヘッドが節約されました。

損益分岐点は概ね: このツールは典型的なセッションで複数回発火するか? イエスなら MCP。ノーなら CLI です。

最適化しなかったもの

  • MAX_MCP_OUTPUT_TOKENS は呼び出し単位で、セッション単位ではありません。 振る舞いの悪いサーバーは、依然として多数のターンにまたがってコンテキストを溢れさせる可能性があります。セッション単位のキャップはまだありません。これは Claude Code の機能リクエストであり、ローカルで修正できるものではありません。
  • Tool Search はオンかオフです。 スキルのように MCP サーバーを階層化することはできません。24 個すべてが一様に Tool Search を通過します。ほぼすべてのセッションで使うサーバーには、eager 読み込みの方が実際には効率的でしょうが、Tool Search をグローバルに無効化せずに、そのサーバーのスキーマだけを選択的に eager 読み込みすることはできません。
  • 私たち自身のワークロードでルーティング精度を慎重には測定していません。 Anthropic の Opus 4 における 49% → 74% は心強く、実運用ではルーティング失敗は見ていませんが、Statnive 固有のタスクで遅延読み込みが eager 読み込みと同じくらいうまく機能することを証明するベンチマークスイートはありません。

今これを行うなら、実用的なステップ

  1. 新しいセッションで /context を実行する。実際に何が読み込まれているかを確認する。
  2. MCP ツールスキーマが 〜20K トークン (ウィンドウの 10%) を超えているなら、Tool Search は自動的に有効になっているはず。/context 出力で確認する。
  3. 上位 3 つの最重コネクタを監査する。パレート曲線は容赦ない。通常 3 つのサーバーが MCP オーバーヘッドの 60% 以上を消費する。
  4. 自分が制御できる MCP サーバーで CRUD 爆発を統合する。
  5. 説明がマーケティングコピーのように読めるツールの説明を削る。
  6. 時々しか使わないツールを MCP から CLI に移す。
  7. MAX_MCP_OUTPUT_TOKENS を妥当な呼び出し単位の上限にキャップする (私たちは 4,000 を使用)。

全体像 — これがどう CLAUDE.md 最適化とスキル階層化と組み合わさって乗算的な節約をもたらすか — に関心があれば、このシリーズの旗艦記事から始めてください。

Statnive を試す

すべてのトークンの行き先に注意を払うチームが提供する、プライバシー重視の WordPress アナリティクス。WordPress.org から Statnive を無料インストール — データはサーバーに留まります。

Statnive を無料で入手