# MCPキャッシュ設計——ttlMsとcacheScopeの決め方

> MCP 2026-07-28仕様はtools/list等にttlMsとcacheScopeの付与を必須化した。TTLの目安と、権限別の一覧でpublicを誤用しない設計を中小企業向けに整理する。

- Canonical: https://kuucorp.com/blog/mcp-cacheable-result-ttlms-cachescope-smb/
- Date: 2026-10-27
- Last modified: 2026-10-27
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
自社のMCPサーバーに接続するクライアントが増えるほど、`tools/list` は同じ内容を何度も返すだけの処理になります。2026-07-28仕様では、この一覧取得にキャッシュのヒントを付けることがサーバー側の必須要件になりました。設定を誤ると、他人向けの一覧が別の利用者に配られる事故にもつながります。

## MCPのキャッシュ仕様で何が必須になったか

> 2026-07-28仕様では、tools/listなどの完了結果にttlMsとcacheScopeを付けることが、サーバーに求められます。

対象は `server/discover`・`tools/list`・`prompts/list`・`resources/list`・`resources/templates/list`・`resources/read` の6操作です。`resultType` が `complete` の結果だけが対象で、追加入力を求める `input_required` の中間結果や、`inputResponses`・`requestState` を伴う再試行の結果は、キャッシュしてはなりません。

キャッシュの単位は、メソッドと結果に影響するパラメータの組です。ページネーションなら `cursor` ごとに別のキャッシュになります。

## ttlMsはどう決めればよいか

> ttlMsは「何ミリ秒は再取得しなくてよいか」を示す鮮度の目安で、HTTPのmax-ageに近い意味を持ちます。

値は0以上でなければなりません。0は即時に古い扱いで、クライアントは毎回取り直せます。クライアントは受信時刻から `ttlMs` の間だけ結果を新鮮とみなし、期限が切れたら次に必要になった時点で再取得します。仕様は、TTLを定期ポーリングの間隔として使うことを推奨していません。

保証ではなく目安である点が重要です。TTL内にサーバー側のデータが変わっても構いません。そのため、次の方針で決めると運用しやすくなります。

- ツール定義を頻繁に更新しない社内サーバー: 300000（5分）程度から始める（仕様の例も300000）
- リリース直後で定義が動く時期: 短くするか0にする
- `listChanged` を宣言している場合: 通知を受けた時点でキャッシュは即時に無効扱いになるので、TTLを長めにしても差し替えは遅れない

仕様は、`listChanged` なしで `ttlMs` だけを返す構成も認めています。その場合クライアントはTTLだけを頼りにします。

## cacheScopeでpublicとprivateをどう使い分けるか

> publicは全利用者に同じ内容を返す応答、privateは利用者や権限ごとに内容が変わる応答に付ける値です。

`public` の応答は、クライアントや共有ゲートウェイが他の利用者にも配ってよいものです。`private` は同じ認可コンテキスト内でのみ再利用でき、アクセストークンが違えばキャッシュも分けなければなりません。

注意点は、`tools/list` が権限によって返す内容を変えてよいことです。付与されたスコープに応じて一部のツールだけを返す実装では、`public` を付けてはいけません。仕様は、認証済みエンドポイントの `public` な応答が、別のアクセストークンの利用者にも共有されうると明記しています。

また、`cacheScope` はアクセス制御の代わりになりません。サーバーはプリミティブごとの認可を、キャッシュとは別に実装します。ページネーションする一覧では、全ページで同じ `cacheScope` を返す必要もあります。

## 中小企業が最初に入れるべき実装は何か

> 最初の一歩は、一覧を決まった順序で返し、ttlMsを一律で付け、権限で変わる一覧だけprivateにすることです。

1. `tools/list` を決定的な順序で返す。仕様はクライアントのキャッシュとLLMのプロンプトキャッシュのヒット率向上を理由に挙げている
2. 全一覧に `ttlMs` と `cacheScope` を付ける。迷う間は `ttlMs` を短く、権限で出し分けるなら `private`
3. 定義を差し替えるリリース手順に、`listChanged` 通知か短いTTLの確認を入れる

旧バージョンのサーバーが `ttlMs` を返さない場合、クライアントは0（即時に古い）として扱います。移行の全体像は[MCP 2026ステートレス仕様の移行ガイド](/blog/mcp-2026-stateless-spec-migration-guide/)、一覧取得の分割は[MCPのページネーション設計](/blog/mcp-pagination-cursor-list-operations-smb/)も参照してください。

## 参考

- [Caching — MCP Specification 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching)
- [Tools — MCP Specification 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
- [Key Changes — MCP Specification 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/changelog)

## まとめ

> ttlMsは再取得の目安、cacheScopeは共有してよい範囲を示す値で、権限別の一覧にpublicを付けないことが最大の注意点です。

一覧の順序固定、`ttlMs` の付与、権限別一覧の `private` 指定の3点を押さえれば、負荷軽減と情報漏えい防止を両立できます。MCPサーバーの本番設計や仕様移行でお困りの際は、[Kuuの運用管理サービス](https://kuucorp.com/services/ai-ops/)にご相談ください。
