約 3 分で読めます

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

自社の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ステートレス仕様の移行ガイド、一覧取得の分割はMCPのページネーション設計も参照してください。

参考

まとめ

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

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

関連記事

MCPとFunction callingの使い分け——ツール設計の選択基準ETagでAIツールの上書き競合を防ぐIf-Match設計MCPクライアントのiss検証とissuer紐付け実装x-mcp-header設計——引数をHTTPヘッダーで制御する