Claude Media
MCPのトークンオーバーヘッドを抑える設定
Claude CodeMCPTips

MCPのトークンオーバーヘッドを抑える設定

Claude CodeでMCPサーバーを複数繋ぐとツール定義がコンテキストを圧迫します。Tool Searchの閾値・サーバー整理・alwaysLoadで消費を絞り込む方法をまとめます。

読了目安 約8分

MCPサーバーが多いとなぜコンテキストを圧迫するか

Claude Codeは、MCPのツール定義を既定で遅延読み込みにしています。セッション開始時にコンテキストへ載るのは、ツール名とサーバーの説明文だけです。フルスキーマは、Claudeが実際にそのツールを使う場面でTool Search経由で読み込まれます。サーバーごとのツール数に固定の上限はありませんが、ツール名とサーバー命令の分だけは、接続するサーバーが増えるほど確実に積み上がります。

サーバーの命令とツールの説明は、それぞれ2KBで切り詰められます。重要な情報は冒頭に書いておくと、切り詰められても要点が残ります。

MCPのツール名とサーバー命令は、セッション開始前に読み込まれる要素の一部にすぎません。Claude Codeは最初のプロンプトを送る前に、CLAUDE.md・自動メモリー・MCPツール名・スキルの説明文をまとめてコンテキストへ載せます。CLAUDE.mdが肥大している環境では、MCPサーバーを整理してもコンテキスト全体の圧迫は残ります。/contextでカテゴリー別の内訳を見て、実際にどこがボトルネックになっているかを先に確認すると無駄な調整を避けられます。

ENABLE_TOOL_SEARCHで遅延読み込みの閾値を調整する

設定値挙動
未設定(既定)挙動全ツールを遅延読み込み。プロキシ経由や一部モデルでは自動で起動時の一括読み込みにフォールバック
true挙動全ツールを常に遅延読み込み(例外は下記)
auto挙動ツール定義の合計がコンテキストウィンドウの10%未満なら起動時に一括読み込み、10%に達したら遅延に切り替え
auto:N挙動閾値をN%(0〜100)に変更
false挙動全ツールを起動時に一括読み込み(遅延なし)
ENABLE_TOOL_SEARCH=auto:5 claude

Tool Searchはtool_referenceブロックに対応したモデルが必要です。Claude Sonnet 4.5・Claude Haiku 4.5・Claude Opus 4.5以降が対象で、非対応モデルの環境ではClaude Codeが起動時の一括読み込みに切り替えます。Google Cloud's Agent Platformでは、Claude 4.5世代以降のモデルはAnthropic APIと同じくTool Searchが既定で有効ですが、それより古い世代のモデルはサービング基盤の制約でツールを起動時に一括読み込みします。ENABLE_TOOL_SEARCH=trueを指定してもこの世代差は上書きできません。

Microsoft FoundryのAzureホスト環境は、Tool Search自体をサーバー側で拒否します。Claude Codeはこの拒否を検知すると、そのデプロイメントに限ってMCPツールを起動時に一括読み込みへ自動で切り替えます。

使わないサーバーを/mcpで無効化する

/mcpパネルでは、接続中の各サーバーのツール数を確認できます。しばらく使っていないサーバーがあれば、設定を残したままトグルで無効化できます。設定は消えないため、必要になったらすぐに戻せます。

無効化した選択は、プロジェクトごとに~/.claude.jsonへ記録されます。既定で有効なサーバーを止めたものはdisabledMcpServersリストに、既定で無効なサーバーを有効にしたものはenabledMcpServersリストに入り、Claude Codeはこの2つを混同しません。設定ファイルを直接編集しなくても、/mcpのトグル操作だけでこの切り替えが完結します。

gh・aws・gcloud・sentry-cliのようなCLIツールは、同等機能のMCPサーバーよりコンテキスト効率に優れます。ツール一覧をコンテキストに載せる必要がなく、Claudeが直接コマンドを実行できるためです。使用頻度の低いMCPサーバーをCLIツールに置き換えるだけでも、常時載る分の消費が減ります。/mcpパネルは、ツール利用を謳いながら実際には1つもツールを公開していないサーバーにも警告を出します。名前だけがコンテキストに載って何の役にも立っていないサーバーを見つける手がかりになります。

プラグインが持ち込むMCPサーバーも見落とさない

MCPサーバーは、自分でclaude mcp addしたものだけとは限りません。プラグインはMCPサーバーを内蔵でき、有効化すると同時に自動で起動します。手動で追加した記憶がなくても、インストール済みのプラグインの数だけサーバーが増えていることがあります。

プラグイン由来のサーバーはclaude mcp addやclaude mcp removeでは管理できず、増減はプラグイン自体のインストール・アンインストールに紐づきます。ただし接続だけを止めたいなら、通常のサーバーと同じように/mcpでトグルを切れます。使っていないプラグインが増えていないか、定期的に棚卸しする価値があります。

alwaysLoadは毎ターン必要なツールだけに絞る

毎ターン確実に使うツールがある場合、Tool Searchの検索ステップを挟まず常時ロードしたいことがあります。サーバー設定にalwaysLoad: trueを加えると、そのサーバーの全ツールがセッション開始時からコンテキストに載ります。

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

個別ツール単位で常時ロードしたい場合は、ツールの_metaに"anthropic/alwaysLoad": trueを加える方法もあります。常時ロードするツールが増えるほど、Tool Searchで浮くはずだったコンテキストは目減りします。本当に毎ターン必要なツールだけに絞り込みます。

alwaysLoad: trueにしたサーバーは、起動時の接続を待ってからセッションが始まります(標準の5秒接続タイムアウトが上限)。他のサーバーは既定でバックグラウンド接続のため、この待ちは発生しません。

自分でMCPサーバーを作る場合のオーバーヘッド対策

社内向けにMCPサーバーを自作している場合、サーバー命令の書き方がTool Searchの精度を左右します。Claudeはサーバー命令を手がかりに、いつそのサーバーのツールを検索すべきかを判断します。扱うタスクのカテゴリー・検索すべき場面・主要な機能を、2KBの上限を意識して冒頭にまとめておくと、必要な場面で確実に検索されるようになります。

命令が曖昧だと、Claudeが適切なタイミングで検索してくれません。結局あらゆるタスクで手探りの呼び出しが増え、かえってコンテキストを余計に消費することになります。

/contextで実際の消費量を確認する

ツール定義そのものだけでなく、ツールが返す出力もコンテキストを消費します。出力の上限は環境変数MAX_MCP_OUTPUT_TOKENSで調整できます。既定値や警告閾値との関係、サーバー側の個別上限との使い分けはMAX_MCP_OUTPUT_TOKENSとはにまとめています。

設定を変えた効果は、体感ではなく/contextコマンドで確認します。カテゴリー別のコンテキスト内訳と最適化の提案が表示され、どのMCPサーバーがどれだけの場所を取っているかが分かります。サーバーが接続できていないだけでツール一覧が読み込まれていないケースもあるため、消費が想定より少ないときは接続状態も併せて確認します。接続の切り分け手順はMCPサーバーに接続できないときの切り分け手順にまとめています。

Tool Searchはツール数の上限を外したが、コンテキスト予算までは外していない

Claude Codeは、MCPサーバーごとのツール数に固定の上限を設けていません。実質的な制限は、Tool Searchが遅延させたあとに残るコンテキストウィンドウの予算そのものです。サーバーを際限なく増やしても起動は止まりませんが、ツール名とサーバー命令の分だけ、静かに予算は減っていきます。整理の手間を惜しむと、この目減りに後から気づくことになります。

よくある質問

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

起動が止まることはありません。Claude Codeは、MCPサーバーごとのツール数に固定の上限を設けていないためです。ただしTool Searchが遅延させたあとも、ツール名とサーバー命令の分だけコンテキストが消費されるため、サーバー数が多いほど残りの予算は減ります。

サーバー命令やツールの説明を長く書いても問題ありませんか

2KBを超えた分は切り詰められます。Claudeがいつ検索すべきかを判断できるよう、カテゴリーや検索すべき場面といった重要な情報を冒頭に書きます。

ENABLE_TOOL_SEARCHはどのプロキシ環境でも使えますか

ANTHROPIC_BASE_URLが非公式のプロキシを指している場合、多くのプロキシがtool_referenceブロックを転送しないため、Claude Codeは既定でTool Searchを無効にします。ENABLE_TOOL_SEARCHを明示的に設定するとこのフォールバックを上書きできますが、プロキシ側が対応していないとリクエストが失敗します。

alwaysLoadを設定したサーバーは起動を遅くしますか

はい。そのサーバーのツールが最初のプロンプト構築までに揃っている必要があるため、起動時に接続を待ちます。待ちは標準の5秒接続タイムアウトが上限です。

プラグインを無効化すれば、そのMCPサーバーの分の消費は消えますか

はい。プラグインをアンインストールすると、内蔵していたMCPサーバーも一緒に削除されます。使わなくなったプラグインをそのまま残していると、気づかないままサーバーが起動し続けます。

まとめ

複数のMCPサーバーを繋いだ状態で運用するチームほど、この整理は効いてきます。MCPのトークンオーバーヘッドは、Tool Searchの遅延読み込みだけでは完全にゼロになりません。使わないサーバーを/mcpで整理し、ENABLE_TOOL_SEARCHの閾値を環境に合わせ、alwaysLoadは本当に毎ターン必要なツールだけに絞る。効果は/contextで確認しながら調整します。

プラグイン経由で増えたサーバーは/mcpのトグルで一時的に止められますが、根本的に減らすには使っていないプラグインのアンインストールまで見直します。設定を1回整えて終わりにせず、サーバーやプラグインを追加するたびに/contextで内訳を見直す習慣にすると、オーバーヘッドが静かに積み上がるのを防げます。

契約全体のコスト管理やチーム展開時の上限設定はClaude Codeのコスト管理、claude mcp addの構文からスコープ設計まではClaude Code MCP設定ガイドにまとめています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →