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

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

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

MCPは、セッション開始前に読み込まれる要素の一部にすぎません。Claude Codeは最初のプロンプトを送る前に、CLAUDE.md・自動メモリー・MCPツール名・スキルの説明文をまとめてコンテキストへ載せます。CLAUDE.mdが肥大している環境では、MCPサーバーを減らしても全体の圧迫は残ります。

/contextならカテゴリー別の内訳と最適化の提案が見られます。

出どころ別にMCPサーバーを止める

サーバーを減らす前に、そのサーバーがどこから来たのかを見分ける必要があります。出どころによって止め方が違うためです。

コネクタの表示名はclaude.ai Slackのようにclaude.aiから始まります。登録済みのサーバーはclaude mcp listで一覧できます。

claude mcp list

出力は次のような形です(名前とURLは例示用の架空のものです)。

Checking MCP server health…
 
claude.ai Example: https://example.invalid/mcp - ✔ Connected
my-other-server: https://example.invalid/mcp (HTTP) - ! Needs authentication
my-server: https://example.invalid/mcp (HTTP) - ✘ Failed to connect

手動で追加した覚えのないサーバーがここに並んでいたら、コネクタかプラグイン由来を疑います。claude mcp get <名前>で1件ずつ詳細を見られます。

状態の表示は接続結果だけではありません。.mcp.jsonのプロジェクトサーバーでまだ承認していないものは⏸ Pending approval、プロジェクトのdisabledMcpServersで止めたものは⊘ Disabled for this projectと出ます。この2つは、サーバーへ接続せずに設定上の判断だけを表示します。⊘が出たサーバーは、次節の/mcpパネルから再び有効にできます。WebSocketサーバーはclaude mcp listに出ないため、claude mcp get <名前>か/mcpパネルで確認します。

/mcpのトグルは何を書き換えるか

/mcpパネルでは、接続中の各サーバーのツール数を確認できます。ツール機能を宣言しているのにツールを1つも公開していないサーバーには、フラグが付きます。名前だけがコンテキストに載って役に立っていないサーバーを見つける手がかりです。

トグルで無効にした選択は、プロジェクトごとに~/.claude.jsonへ記録されます。既定で有効なサーバーを止めたものはdisabledMcpServersに入ります。対象は自分で追加したサーバー・プラグインのサーバー・組織が配るサーバー・取得済みのコネクタです。computer-useのように既定で無効の組み込みサーバーを有効にしたものはenabledMcpServersに入ります。

Claude Codeは1つのサーバーにつき片方のリストしか参照しません。通常のサーバーをenabledMcpServersに書いても、無視されます。

gh・aws・gcloud・sentry-cliのようなCLIツールは、同等機能のMCPサーバーよりコンテキスト効率に優れます。ツール単位の一覧がコンテキストに載らず、Claudeが直接コマンドを実行できるためです。使用頻度の低いMCPサーバーは、CLIへの置き換えも選択肢です。

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

ENABLE_TOOL_SEARCH=auto:5 claude

同じ値は、settings.jsonのenvフィールドにも書けます。毎回コマンドの前に付けたくない場合の置き場所です。

Tool Searchはtool_referenceブロックに対応したモデルが必要です。Claude Sonnet 4.5・Claude Haiku 4.5・Claude Opus 4.5以降が対象です。

Google Cloud's Agent Platformでは、Claude 4.5世代以降のモデルはAnthropic APIと同じくTool Searchが既定で有効です。それより古い世代のモデルは、サービング基盤の制約でツールを起動時に一括読み込みします。ENABLE_TOOL_SEARCH=trueを指定してもこの世代差は上書きできません。

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

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定していると、Tool Searchはオフのままになり、ENABLE_TOOL_SEARCHでは上書きできません。組織がTool Searchを維持したい場合は、v2.1.227以降でmanaged settingsから上書きできます。

ToolSearchツールだけを止めたいときは、権限のdenyに指定する方法もあります。

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

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

毎ターン確実に使うツールがあるなら、Tool Searchの検索ステップを挟まず常時ロードする手があります。サーバー設定にalwaysLoad: trueを加えると、そのサーバーの全ツールがENABLE_TOOL_SEARCHの値にかかわらずセッション開始時からコンテキストに載ります。alwaysLoadはすべてのサーバー種別で使えます。

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

個別ツール単位なら、ツールの_metaに"anthropic/alwaysLoad": trueを加えます。常時ロードするツールが増えるほど、Tool Searchで浮くはずだったコンテキストは目減りします。

リモートサーバーに有効なcachedエントリがあれば、キャッシュからツール一覧を取れるため、接続を待たずに起動が進みます。/mcpやプラグインの管理画面ではcached 2h ago · connects on first use · 5 toolsのように表示され、サーバーへの接続は、Claudeがそのサーバーのツールを初めて呼ぶ時点まで遅れます。この発見キャッシュはv2.1.221以降の機能です。既定ではオフで、段階的なロールアウトで有効になっているアカウントもあります。MCP_DISCOVERY_CACHE=1で有効、0ならロールアウトで有効になっていてもオフのままにできます。v2.1.238より前は既定で有効でした。

alwaysLoadの待ち時間の上限は環境変数MCP_CONNECT_TIMEOUT_MSで決まり、既定は5000ミリ秒です。MCP_CONNECTION_NONBLOCKING=0を設定すると逆向きになります。alwaysLoadでないサーバーも含め、起動時に全サーバーの接続を待つようになります。

ENABLE_TOOL_SEARCH=falseやカスタムのANTHROPIC_BASE_URLなど、Tool Searchを使わない構成では、接続中のサーバーを待つ役目をWaitForMcpServersツールが担います。

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

社内向けにMCPサーバーを自作している場合、サーバー命令の書き方がコンテキスト消費に直結します。protoファイルからMCPサーバーを生成して社内gRPCサービスを呼ぶ手順はgRPCサービスをMCP化するにあります。

サーバー命令は既定で2,048文字までしか載りません。環境変数CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH(v2.1.280以降)で上限は変えられます。サーバー命令は、Claudeがツールをいつ検索すべきかを判断する手がかりになります。扱うタスクのカテゴリーと、いつ検索すべきか、主要な機能の3点を、上限を意識して冒頭に書いておきます。1サーバーあたりのツール数に固定の上限はなく、実際の限界はコンテキストウィンドウの予算です。ツールの説明も同じ上限で切られるため、1つのツールに長い使い方の解説を詰め込む設計は向きません。

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

ツール定義そのものだけでなく、ツールが返す出力もコンテキストを消費します。MCPツールの出力が10,000トークンを超えると警告が出て、既定では25,000トークンで打ち切られます。上限は環境変数MAX_MCP_OUTPUT_TOKENSで引き上げられますが、警告の閾値は固定です。画像を含まない結果が上限を超えると、会話の中ではファイルのパスを示すメッセージに置き換わり、本文はセッションのtool-resultsディレクトリ(~/.claude/projects/の下)に保存されます。Claudeは内容が必要になったときにそのファイルを読みます。サーバー側の個別上限との使い分けはMAX_MCP_OUTPUT_TOKENSとはにあります。

/contextでMCPの消費が想定より少ないときは、サーバーが接続できておらずツール一覧が読み込まれていない可能性もあります。接続の切り分けはMCPサーバーに接続できないときの切り分け手順が手がかりになります。

よくある質問

サブエージェントにもMCPサーバーの定義は載りますか

載ります。サブエージェントは親とは別のコンテキストウィンドウで動きますが、CLAUDE.mdと同じMCP・スキルの構成を読み込み、会話履歴だけを持たない状態で始まります。サブエージェントを多用する運用では、MCPの定義が起動のたびに積み上がります。

まとめ

遅延読み込みが既定でも、サーバー命令とツール名は繋いだ数だけ積み上がります。止める手段は出どころごとに違うので、claude mcp listで出どころを見分けてから手を付けると、無駄な設定変更で遠回りせずに済みます。

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