Claude Codeでプロンプトキャッシュが思ったより効かない。あるいは、拡張思考（extended thinking）が会話の途中で捨てられている気がする。そういうときに最初に疑う場所は、繋いでいるMCPサーバーの「数」ではなく、会話の途中でツール一覧が書き換わっていないかです。2026年9月9日公開のClaude Code 2.1.267には、この同じ原因に紐づく修正が1リリースに11件まとめて入りました。
この記事では、なぜツール一覧の途中変更がキャッシュと思考を壊すのかを先に整理し、11件の修正を3つに分類して、本体を更新した後も運用側に残る対策をまとめます。
対象読者は、Claude CodeにMCPサーバーをいくつか繋いで使っていて、「トークン消費が読みより多い」「/costのキャッシュ行が思ったより悪い」と感じている人です。プロンプトキャッシュの仕組み自体の説明は最小限にするので、初めての方は先に入門記事をどうぞ。
Claude Codeのプロンプトキャッシュ入門｜エージェント運用のコストを観測して設計するClaude Codeを定時実行で運用するときのAPIコストを左右するプロンプトキャッシュの仕組みを解説します。キャッシュが静かに切れる箇所、2026年8月末に追加された/costのキャッシュ行やエージェント別cacheTtlなどの観測・制御手段、日次運用での設計判断をまとめます。www.tentspace.net
ツール定義は「会話の先頭近く」に置かれた大きな塊
前提を2つだけおさらいします。
1つ目。プロンプトキャッシュはプレフィックス一致で効きます。毎ターン送られる内容の先頭からどこまでが前回と完全に同じか、で判定され、途中が1か所でも変われば、そこから後ろのキャッシュは無効です。
2つ目。Claude Codeが毎ターン送る内容の先頭側には、システムプロンプトとツール定義が置かれます。ツール定義には組み込みツールに加えて、接続中のMCPサーバーのツール群が全部含まれる。つまりMCPサーバーを繋ぐほど、会話の先頭近くに大きな塊が積まれる構造です。
この2つを掛け合わせると、こうなります。ツール一覧が会話の途中で変わると、プロンプトの先頭近くが書き換わったことになり、その後ろ——会話履歴のほぼ全部——のキャッシュが作り直しになる。接続台数は「毎ターンの固定コスト」を増やしますが、途中の変更は「積み上げたキャッシュの破棄」を起こす。同じツールまわりの話でも、効き方が別物です。
台数の側の話、つまりツール定義が毎ターンのトークンを常時消費する構造は、MCPの設定ガイドに書きました。この記事はその続きで、「繋いだ後に揺れるとどうなるか」の側です。
Claude CodeにMCPサーバーを追加する設定ガイド｜3つのスコープと.mcp.jsonの使い分けClaude CodeへMCPサーバーを接続する設定方法を解説します。claude mcp addの基本、local・project・userの3スコープの使い分け、.mcp.jsonのチーム共有と環境変数展開、接続確認と権限設定、サーバーを足しすぎない判断軸をまとめます。www.tentspace.net
2.1.267の修正一覧は、同じ原因を11回言っている
一次情報はClaude Code公式のchangelogです（確認日2026-09-10）。
Claude Code公式changelogRelease notes for Claude Code, including new features, improvements, and bug fixes by version.code.claude.com
2.1.267のリリースノートを読んでいくと、不思議な光景に気づきます。「会話の途中でツール一覧やシステムプロンプトが書き換わり、プロンプトキャッシュの再利用が壊れる・以前の思考が捨てられる」という、同じ形の修正が11件並んでいる。MCPサーバー、組み込みツール、サブエージェント、セッション再開、モデル切替と、入口はばらばらなのに、直している場所は全部同じです。
私はここを読んで、見立てをひとつ改めました。キャッシュミスの原因調査というと、つい「どのサーバーを外すか」という台数の引き算を考えます。でもこの修正一覧が示しているのは、繋ぐ本数より「途中で変わること」のほうが、キャッシュには効いていたという構図です（この読み自体は私の解釈で、各修正がどれだけのミスを起こしていたかの実測はありません）。
11件を眺めやすいように、3つに分類します。
分類1: 内容は同じなのに「再描画」で別物になる
1つ目のグループは、ツール定義の中身は変わっていないのに、描画し直すことで同一性が崩れていたケースです。
- MCPサーバーが読み込み済みのツールを再送する、または組み込みツールが再描画されると、それ以前の推論（earlier reasoning）が落ちる
- 再開したセッションが、記録済みのツール説明を「再生」せずに描画し直す
- サブエージェントや
--system-prompt/--append-system-promptで起動したセッションが、システムプロンプトとツール定義を毎回描画し直していた（一度だけ記録する方式へ改善）
人間の目には「同じツールがもう一度並んだだけ」でも、プレフィックス一致の世界では書き換えです。キャッシュの観点では、同じ内容かどうかではなく、バイト列として同一かどうかだけが問われます。
分類2: 途中でツールが増える・消える
2つ目は、ツール一覧そのものが会話の途中で増減するケースです。
- 切断したMCPサーバーや、サーバーのアップグレードによって、会話の途中でツールが消えると、一覧が書き換わって以前の思考が捨てられる
- ToolSearch（ツール定義を必要時に取り寄せる仕組み）の無いセッションで、MCP・pluginのツールが途中から一覧へ追加されると、キャッシュ再利用が壊れる。2.1.267からは、対応モデルへは deferred definitions（遅延定義）として渡す方式へ変わった
- 会話からフォークしたバックグラウンドworkerが、EnterWorktreeツールをツールブロックへ足していた
注目したいのは2点目の直し方です。「追加をやめる」のではなく、「追加してもプレフィックスを壊さない渡し方に変える」。ツールを増やせる柔軟さは残したまま、キャッシュの破棄だけを避ける設計になっています。
分類3: モデル切替とセッション再開が一覧を書き換える
3つ目は、ツールを触ったつもりがないのに、操作の副作用として一覧が書き換わるケースです。
/modelでモデルを切り替えると、全ツール定義が再送されていた（コミット・PRに入るattribution文はモデル変更時に更新される会話ノートとして渡す方式へ変更）- 再開したセッションで、MCPコネクタの再接続タイミングが前回と違うと、インラインのツール集合が書き換わる
- claude.aiコネクタのツールが、セッションと再開の間で変わる
- 再開したセッションが、コネクタの再接続前に以前のMCPツール告知を書き換える
- print mode（
-p）の会話を対話的に再開すると、システムプロンプトのプレフィックスが変わる
セッション再開だけで4件あります。再開は「前回の続きから始める」機能なので、前回と同じプレフィックスを再現できるかがそのまま論点になる。モデル切替も同様で、切り替えたのはモデルなのに、巻き添えでツール定義が全部送り直されていたわけです。
壊れるのはコストだけではない
ここまでキャッシュ＝コストの話として書きましたが、11件の修正文に繰り返し出てくるもうひとつの被害が「以前の思考が捨てられる」です。
拡張思考を使うセッションでは、モデルがそれまでに積んだ推論の上に次の判断を重ねます。ツール一覧の書き換えでこの推論が捨てられると、増えるのは請求だけではなく、「さっきまでの検討を忘れた状態で続きを考える」という挙動面の劣化も起きうる。キャッシュミスは /cost の数字に出ますが、思考の破棄は数字に出にくい分、こちらのほうが気づきにくい問題だと思います。
切り分けの手順: どの系統かをセッションの履歴から当てる
自分のセッションで「キャッシュが悪いのはどの系統のせいか」を切り分けるときは、派手な計測より、セッション中に何をしたかの振り返りが近道です。順番にこう見ます。
まず /cost でキャッシュ行を確認し、ミスが「そもそも大きいのか」を見ます。定時実行のセッションは毎回cold startから始まるので、初回書き込みの分は正常です。問題にすべきは、セッションの途中、それも会話が十分に進んだ後で発生しているミスのほうです。
次に、そのセッションで次の操作をしたかを思い出します。
/modelでモデルを切り替えたか。 切り替えたなら分類3です。切替の直後のターンはツール定義の再送が乗るので、重くなって当然でした（2.1.267で改善）- 再開したセッションか。
--resumeや--continueで戻った会話なら、これも分類3の候補です。再開まわりだけで4件の修正が入っているので、更新前のバージョンでの再開セッションは、キャッシュの観点では「別の会話」になっていた可能性があります - セッション中にMCPサーバーが切れたか。
/mcpで接続状態を確認できます。切断・再接続を繰り返した形跡のあるサーバーがいれば分類2で、これは本体更新後も運用側で対処が要る、いちばん残る系統です - サブエージェントを多用する構成か。 サブエージェント側のプレフィックス再描画は分類1で、2.1.267の「一度だけ記録する」改善がそのまま効きます。構成を変えなくても、更新だけで挙動が変わる場所です
この切り分けの良いところは、どの系統に当たっても「更新する」「途中で変えない」「不安定なサーバーを外す」のどれかに落ちることです。原因の当たりを付けてから直すので、効果の確認も /cost の前後比較で済みます。
実務での扱い: 更新が先、運用の原則は3つ
では運用側は何をするか。順番に3つです。
1. まず本体を2.1.267以降へ更新する。 11件の大半は本体側の不具合修正なので、運用の工夫より先に更新が効きます。逆に言えば、更新前のバージョンで「MCPサーバーを減らしたのにキャッシュが悪い」と悩んでいた場合、原因は台数ではなくこの系統だった可能性があります。
2. セッションの途中で構成を変えない。 本体が直っても、「会話途中の構成変更がプレフィックスを揺らす」という構造自体は残ります。/model の切り替えやMCPサーバーの追加・削除は、セッションの区切りで行う。接続が不安定で切断と再接続を繰り返すMCPサーバーは、分類2の「途中で消える」を日常的に起こすので、安定するまで定時実行や長時間セッションから外す。設定ガイドでは「繋ぐ前の3つの質問」を書きましたが、そこに「セッションの間、安定して繋がり続けるか」を足したい気持ちです。
3. /cost のキャッシュ行で前後を見る。 キャッシュのヒット率とミス数はセッション単位で確認できるようになっています。更新や構成固定の効果は、感覚ではなくここで確かめるのが確実です。
私の環境も、複数のMCPサーバーを繋いだままサブエージェント込みで定時実行を回す構成なので、この11件はそのまま自分の話です。方針としては、TTLの調整のような積極策より先に、本体の更新とツール構成の固定という地味な側を置きます。プレフィックスの安定はキャッシュ設計の前提条件で、前提が揺れているうちは、上に何を積んでも効きが読めないからです。
まとめ
- Claude Codeのプロンプトキャッシュはプレフィックス一致で効き、ツール定義は会話の先頭近くに置かれる。だから会話途中のツール一覧変更は、積み上げたキャッシュの破棄と拡張思考の廃棄を同時に起こす
- 2.1.267では、この同じ原因に紐づく修正が1リリースに11件入った。内訳は「再描画で別物になる」「途中で増減する」「モデル切替・セッション再開の副作用」の3系統
- ToolSearchの無いセッションへの途中追加は、deferred definitionsとして渡す方式へ変わった。追加を禁じるのではなく、追加してもプレフィックスを壊さない方向の設計
- 運用側の対策は、2.1.267以降への更新、セッション途中で
/modelやMCP構成を変えないこと、/costのキャッシュ行での前後確認の3つ - MCPサーバーの接続台数は毎ターンの固定コスト、途中の変更はキャッシュの破棄。台数を絞ってもキャッシュが悪いときは、「途中で変わっていないか」を疑う
キャッシュの仕組みと観測手段の全体像は入門記事に、MCPサーバーを繋ぐ側の判断は設定ガイドにまとめてあります。この記事の「揺らさない」原則とあわせて、3本でひとつの設計になります。