Claude CodeでMCPサーバーを繋ぐとプロンプトキャッシュが壊れる——公式docsとGitHub Issueで条件を確認した
Claude CodeでMCPサーバーの接続・切断がプロンプトキャッシュを無効化しコストが跳ね上がる問題を、公式docsとGitHub Issue #92033の実測データから条件別に整理した。
エンジニアのゆとです。
MCPサーバーをいくつも繋いでClaude Codeを使っていると、セッションの途中から急にレスポンスが遅くなって、/costや/usageを見たらキャッシュ書き込みのトークン数がやたら多い——という場面に出くわすことがある。原因を探ると大体「MCPサーバーの接続・切断がプロンプトキャッシュを無効化する」という話に行き着くんだけど、これが公式ドキュメントを読むと実は単純じゃない。
「デフォルトなら基本安全」と書いてある一方で、GitHub Issueには実際のセッションログ付きで「800Kトークン単位の書き込みが1分間隔で発生した」という報告が上がっている。両方とも嘘は書いていない。条件が違うだけだ。この記事では公式docsとGitHub Issue #92033を中心に、何が起きていて、自分がどっちの条件に当てはまるのかを整理する。
結論から: 自分が当てはまる条件はどれか
| 条件 | MCPサーバーの接続/切断でキャッシュは壊れるか | 理由 |
|---|---|---|
| 対応モデル + ツール検索(Tool Search)が有効(デフォルト) | 基本的に壊れない | ツール定義が「遅延」され、システムプロンプトのキャッシュ済みプレフィックスに含まれないため |
ツール検索が無効・利用不可(カスタムANTHROPIC_BASE_URLゲートウェイ、Claude 4.5世代より前のGoogle Cloud Agent Platformモデルなど) | 壊れる | ツール定義がプレフィックスに読み込まれ、接続・切断のたびに再計算対象になる |
alwaysLoad指定のサーバー・しきい値ベースで前もって読み込まれるツール | 壊れる | 同上。デフォルト回避の対象外として明示的に前倒しで読み込まれる |
| ツール検索は有効だが、複数MCPサーバーを使っていてどれか1つの構成が変わった | ケースによる | GitHub Issue上ではツール検索有効時でも”配列内の並び順”が原因でカスケード無効化が起きたという実測報告がある(後述) |
自分の状況がどれに近いか分からない場合は、まず後述の「自分の環境で影響を受けているか確認する方法」から先に見てもらってもいい。
何が起きているか: GitHub Issueの実測データ
Issue #92033の報告者は、Max 5xプランで36時間にわたって断続的に--resumeしながら使っていた1セッションのトランスクリプトを提示している。抜粋するとこうだ。
時刻 cache write cache read 備考
07:47:37 857,710 39,062 フル書き込み(高い)
07:47:50 3,032 896,772 キャッシュ正常
07:48:20 3,331 899,804 キャッシュ正常
07:48:32 deferred_tools_delta / agent_listing_delta / mcp_instructions_delta が発火
07:48:49 782,873 10,138 フル書き込み(高い)、直前の正常ターンからわずか1分後3ターン連続でキャッシュ読み込みが897K→900K→903Kと正常に伸びていたのに、deferred_tools_deltaなどのイベントが発火した直後のターンで、いきなり78万トークン超のフル書き込みが再発生している。報告者はこれを「5時間分のMaxプラン使用量を、実質10分以内の操作で溶かした」と表現している。
この報告に他のユーザーが検証結果を寄せていて、内容がさらに具体的になっている。
- Issue #91514:
ToolSearchやSkill呼び出しの直後に、752Kあった温かいキャッシュが約33Kまで一気に縮小し、726Kトークンが再書き込みされた - Issue #81967: 1,821件のAPIリクエストを計装して調べたところ、ツール配列(
tools)の変更によるキャッシュ無効化が、TTL切れによる無効化より大きくなるケースがあった - 独立した集計(506セッション・約3.2GBのログ): キャッシュ破壊によって再課金されたトークンは合計2億2,440万トークン、破壊イベント2,766回、うちツール/スキル/MCPリスト変更が絡むものが1,399回(全セッションの38%)。これによる再課金額はコーパス全体の支出の13.5%を占めていた
公式docsは「デフォルトなら安全」と言っている
ここで公式ドキュメントを確認すると、Anthropic自身がこの挙動を明文化している。「MCPサーバーの接続または切断」というセクションにこう書かれている。
遅延ツール、サポートされているモデルのデフォルト: サーバーの接続、切断、またはツールリストの変更は、新しいコンテンツのみを追加し、既にキャッシュされているものを妨害しません。
プリフィックスに読み込まれるツール: それらへの変更はキャッシュを無効にします。これはツール検索が利用不可または無効な場合に発生します。
つまり建前としては「ツール検索(Tool Search)によってMCPのツール定義が遅延読み込みされている状態なら、サーバーの接続や切断はキャッシュ済みプレフィックスの後ろに追加されるだけで、既存のキャッシュは壊れない」という設計になっている。ドキュメントはツール検索が効かない具体例として、カスタムANTHROPIC_BASE_URLゲートウェイ、Claude 4.5世代より前のGoogle Cloud Agent Platformモデル、alwaysLoad指定のサーバー、しきい値ベースの前倒し読み込みを挙げている。
この条件に当てはまらない一般的な使い方——Claude Max/Proプランで公式クライアントをそのまま使っている場合——であれば、ドキュメント通りならMCPサーバーの接続・切断そのものは無害ということになる。
それでも壊れる理由: 並び順が引き起こすカスケード無効化
ところがIssue #92033には、ツール検索が有効な環境でも実際にキャッシュが壊れたという検証結果が投稿されている。投稿者(nikolai-vysotskyi氏)はclaude -pの連続実行から取得した実際のリクエストボディ(137ツール・223,322文字のtoolsブロック)を分析し、次の構造を見つけている。
- ツール定義は情報源(built-in、各MCPサーバー)ごとに連続したブロックとして並んでいて、順序自体は2回のセッション間でバイト単位まで一致していた
- 並び順は「built-inが先頭、その後はサーバー名のアルファベット順」になっていた
- あるMCPサーバーの構成が変わると、そのサーバーより後ろに並んでいる全てのサーバーのツール定義も道連れで無効化される
実測された影響度はこうだ。
| 変更したサーバー | 無効化されるtoolsの割合 | 概算トークン数 |
|---|---|---|
| Gmail | 52.6% | 約29,400 |
| Google Drive | 27.3% | 約15,200 |
| context7 | 21.3% | 約11,900 |
| chrome-devtools | 19.4% | 約10,800 |
| trace-mcp | 6.1% | 約3,400 |
さらに投稿者は「アルファベット順で先頭に近いサーバー名(airtableなど)を新規追加すると、それより後ろの全サーバーが道連れで再計算される」と指摘している。名前が早いサーバーを増やすたびに、影響範囲が雪だるま式に広がる設計だということだ。
つまり「ツール検索が有効だから安全」という公式説明は、少なくとも複数のMCPサーバーを併用していて、かつそのうちどれかの構成(接続/切断/ツールリスト変更)が変わる場面では、並び順次第で無効化が波及するケースがあるとみていい。この並び順の話は公式docsには明記されていない、Issue側の独自検証だという点は留意しておきたい。
自分の環境で影響を受けているか確認する方法
まず/usageを実行する。Claude Code v2.1.260以降ならPrompt cache (main)の行に「直近のキャッシュミスの推定原因」が表示されるようになっていて、likely cause: tool definitions changedのような形で出る。これが頻発しているなら、MCP/ツール構成の変化が原因の可能性が高い。
もう少し定量的に見たいなら、ヘッドレスモードで--output-format jsonを使ってusageフィールドを直接確認する方法もある。
claude -p "同じ質問をもう一度" --output-format json出力に含まれるcache_read_input_tokens(安い方)とcache_creation_input_tokens(高い方)の比率を、MCPサーバーを追加・削除するタイミングの前後で比較する。書き込みだけが跳ね上がるタイミングがMCP操作と一致しているなら、この記事で扱っている問題の影響を受けている可能性が高い。使用量の見方自体はこちらの記事でも詳しくまとめている。
現状の対処法
Issue自体はまだオープンで、根本的な修正(ツール定義の並び順の安定化、または並び順に依存しない無効化ロジックへの変更)は2026年9月13日時点で入っていない。今すぐできる対処は条件によって変わる。
1. まずツール検索(Tool Search)が有効かどうかを確認する
カスタムゲートウェイや一部のクラウド経由での利用でないなら、多くの場合デフォルトで有効になっているはずだ。無効化されている心当たりがある場合は、その設定を見直すだけでMCP関連の無効化はかなり減る可能性がある。
2. 使用頻度の低いMCPサーバーはalwaysLoadにしない
alwaysLoadはツール検索による遅延読み込みの対象外になる設定なので、常時使わないサーバーにまで付けているとキャッシュ無効化のリスクを自分で増やすことになる。
3. セッション途中でのMCPサーバーの追加・削除を避ける
作業の合間にMCPサーバーを頻繁に足したり外したりする使い方をしていると、そのたびに無効化の引き金を引いている可能性がある。使うサーバーはセッション開始時点である程度確定させておいた方が、キャッシュヒット率は安定しやすい。
4. それでも改善しない場合、サードパーティの緩和ツールという選択肢もある
ツール検索が構造的に使えない環境(Bedrock/Vertex経由など)で、かつコスト影響が無視できない規模になっている場合は、claude-code-cache-fixというOSSのローカルプロキシを挟むという選択肢がIssueのコメント欄で紹介されている。ブロックの並び順を毎リクエスト正規化し、cache_controlが剥がれないようにする、という仕組みだ。
npm install -g claude-code-cache-fix
node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" &
ANTHROPIC_BASE_URL=http://127.0.0.1:9801 claudeただし、これは公式ツールではなく個人が公開しているサードパーティ製プロキシだ。API通信の中身を読み書きする以上、導入するなら中身を自分で確認してから使うべきだし、ANTHROPIC_BASE_URLを独自のプロキシに向けること自体が、公式docsの言う「カスタムゲートウェイ」に該当してキャッシュの扱いが変わる点も理解した上で判断した方がいい。業務利用や機密性の高いプロジェクトでは特に慎重になるべきところだ。
FAQ
ツール検索(Tool Search)はどうやって有効/無効を確認できる
公式docsでは/docs/ja/mcp#configure-tool-searchにツール検索の設定方法がまとめられている。カスタムANTHROPIC_BASE_URLゲートウェイを使っている場合や、Google Cloud Agent PlatformでClaude 4.5世代より前のモデルを使っている場合は無効になっている可能性が高いので、まずそこに該当していないか確認するのが早い。
MCPサーバーを1つしか使っていなくても影響はあるか
構造上は影響を受けにくい。Issue上のカスケード無効化は「複数のMCPサーバーをアルファベット順で並べたときに、変更したサーバーより後ろが道連れになる」という話なので、サーバーが1つならそもそも道連れにする対象が存在しない。ただしツール検索が無効な環境では、その1つのサーバーの接続・切断自体がキャッシュを無効化する点は変わらない。
プラグインが提供するMCPサーバーでも同じことが起きるか
起きる。公式docsは「MCPサーバーを提供するプラグイン」についても、通常のMCPサーバーの接続・切断と同じルールに従うと明記している。ツール検索で遅延されていればキャッシュは保持され、プレフィックスに読み込まれる場合は次のリクエストで会話全体が再計算される。
この問題はいつ修正される見込みか
Issue #92033、#91514、#81967はいずれも2026年9月13日時点でオープンのままで、確定的な修正時期のアナウンスは出ていない。ただし関連する古いIssue #27048(2026年2月報告)は5月にクローズされている実績があるので、まったく手が付けられていないわけではなさそうだ。バージョンアップ時のチェンジログで「cache」「prompt cache」「MCP」あたりのキーワードを確認する習慣をつけておくと見逃しにくい。
まとめ
「MCPサーバーの接続・切断でプロンプトキャッシュが壊れる」という話は、公式docsを読む限り「デフォルトのツール検索が有効なら基本的に無害」という建前になっている。しかしGitHub Issueには、その建前が崩れる具体的な条件——ツール検索が無効な環境、そして複数MCPサーバーの並び順によるカスケード無効化——が実測データ付きで報告されている。
自分が影響を受けているかどうかは、/usageのlikely cause表示か、cache_readとcache_creationの比率をMCP操作の前後で比較すれば大体切り分けられる。まずはそこから確認して、必要ならツール検索の設定見直しやalwaysLoadの棚卸しから手をつけるのがいい。
