MCP 规范新增缓存元数据后客户端如何处理 TTL

MCP 2026-07-28 规范把缓存提示带进了列表和资源结果：客户端会看到 ttlMs 与 cacheScope。真正容易出错的地方不是字段怎么解析，而是把 TTL 误当成服务器强制缓存时间，或者把带有用户数据的结果放进共享缓存。处理这次变化时，可以从“响应什么时候收到、谁可以复用、什么事件会提前失效”三个问题开始。

官方资料：https://modelcontextprotocol.io/specification/2026-07-28/basic/index

变更说明：https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2549-TTL-for-list-results.md

客户端应把 ttlMs 当作从接收时间开始计算的新鲜度提示，把 cacheScope 当作共享边界；TTL 到期时按需重新请求，收到相关变更通知时立即失效。

先看懂 ttlMs 与 cacheScope 分别解决什么问题

这次规范变化针对的是 tools/list、prompts/list、resources/list、resources/read 和 resources/templates/list 等结果。服务器在结果里给出 ttlMs，表示客户端在多长时间内可以把结果视为新鲜；它不是服务器承诺“数据绝不会变化”的保证。

ttlMs 使用整数毫秒。值为 0 时，结果应视为立即过期；正数则从客户端收到响应的时刻开始计算。cacheScope 只有两个关键方向：public 允许共享网关或代理为不同用户复用，private 只能留在请求用户自己的缓存上下文中。

这也解释了为什么客户端不能只读取 TTL。一个工具目录可能一分钟不变，但如果结果随授权用户变化，仍然不能放进多租户共享缓存。换句话说，ttlMs 解决“多久可以复用”，cacheScope 解决“谁可以复用”。

收到结果时先记录接收时间和缓存范围

客户端收到响应时，应该把本地接收时间 t_received 和两个字段一起保存。不要使用服务器生成响应的时间，也不要把 HTTP 传输层的缓存头当成 MCP 的唯一来源，因为 MCP 也可以运行在 stdio 等没有 HTTP 头的传输上。

下面这个 JSON 只展示线路上的字段，JSON 本身不能加入注释，因此字段含义放在代码块外说明：

{
  "tools": [
    {"name": "search", "description": "Search documents"}
  ],
  "ttlMs": 60000,
  "cacheScope": "public"
}

示例表示客户端可以从收到响应开始，把这份结果视为最多 60000 毫秒的新鲜数据；它并不表示客户端必须缓存，也不表示 60000 毫秒内服务器不能改变内容。若 cacheScope 是 private，缓存键还应绑定到请求用户或授权上下文，不能只用服务器地址和 RPC 方法名组成。

客户端访问前怎样判断结果还能不能用

最小判断逻辑可以压缩成一句话：now 时结果仍然新鲜，否则在下一次访问时重新请求。客户端不必因为 TTL 到点就自动轮询；TTL 更像按需访问时的 freshness hint，而不是后台定时器。

package cache

import "time"

type Entry struct {
	ReceivedAt  time.Time
	TTLMS       int64
	Scope       string
	Invalidated bool
}

func (e Entry) Fresh(now time.Time) bool {
	// 通知失效优先级高于剩余 TTL，避免继续使用已经确认变化的结果。
	if e.Invalidated || e.TTLMS 

这个片段只表达决策关系，真正的客户端还需要保存结果正文、分页游标、协议版本和授权上下文。尤其要避免把未知的 cacheScope 当成 public；对于新旧 SDK 混用的环境，默认采用不共享更稳妥。

通知到达时要立即失效，不要等 TTL 自己结束

TTL 和变更通知解决的是两类问题。TTL 适合无状态传输或客户端不想频繁轮询的场景；如果服务器已经发送了相关的 list_changed 通知，客户端就有更强的变化线索，应立即把对应缓存标成失效，然后在下次访问时重新拉取。

这里不建议收到通知就无条件刷新所有缓存。客户端可以按能力类型、资源 URI 或缓存键建立索引，只失效受影响的条目。这样既保留通知的及时性，也避免一条工具列表变化造成整个服务器的缓存抖动。

重新请求失败时怎样处理旧结果

正常路径是过期后重新请求；异常路径则要看读者任务能否接受短暂陈旧数据。规范把 TTL 定义为提示，客户端可以在重新请求失败时采取降级策略，但必须把“旧结果”与“新鲜结果”区分开，不能悄悄延长原 TTL。

旧服务兼容和上线建议

不理解新字段的旧客户端通常会忽略它们，新增字段不会改变既有结果对象的其他成员。反过来，新客户端面对没有 ttlMs 的旧服务时，不应自作主张地给出很长的默认 TTL；按立即过期或已有的保守缓存策略处理，才能保持兼容。

实际接入可以分三步：先只解析并记录两个字段；再在 private 范围内启用短 TTL；最后确认结果确实与用户无关后，才把稳定的列表提升为 public。上线时同时观察缓存命中、过期重取、通知失效和错误降级四类事件，能较快分辨是 TTL 太短、共享范围过宽，还是服务端列表本身缺少稳定性。

常见问题

TTL 到期后客户端必须立刻后台刷新吗？

不必须。更自然的做法是下次真正需要结果时再判断并重新请求；如果产品确实要后台刷新，应加入抖动和退避，避免大量客户端同时到点。

cacheScope 为 public 就一定能放进 CDN 吗？

不一定。它表示结果允许被共享缓存复用，具体仍要结合传输层、授权头、缓存键和网关规则判断，不能跳过基础的身份隔离设计。

tools/call 的结果也要按同样方式缓存吗？

不能直接类推。缓存元数据主要服务于列表和资源读取结果；工具调用往往带有动作和副作用，是否缓存必须另行设计，不能因为看到了 ttlMs 就把调用结果当成可重复读取的数据。

总的来说，MCP 新增的不是一个“服务器替客户端保存结果”的开关，而是一组让客户端更清楚地处理新鲜度和共享边界的提示。先以接收时间计算 TTL，再让通知负责提前失效，最后用 private 和短 TTL 作为上线起点，通常比直接追求高缓存命中更安全。