MCP 资源与工具描述的缓存更新策略

MCP 资源与工具描述要缓存，但不能只设一个固定过期时间。更稳妥的策略是：按请求方法和影响结果的参数建立缓存键，用 ttlMs 控制按需新鲜度，用 cacheScope 隔离授权上下文；同时订阅工具列表、资源列表和指定资源的变更通知，收到通知立即把对应条目标为陈旧，再在下一次需要时重新获取。

MCP 官方地址：https://modelcontextprotocol.io/

我是在做一个多服务器聚合器时真正踩到这个问题的：为了减少每次对话前的请求，我把工具列表和资源目录一起缓存了五分钟。延迟确实降了，但服务器替换了一个工具的输入 schema 后，模型还在按旧描述构造参数；另一边，资源正文已经更新，资源目录却根本没变化。那时我才意识到，“描述缓存”并不是一个缓存，而是至少三类生命周期不同的对象。

问题不只是 TTL 太长

出现旧工具、旧资源时，第一反应通常是缩短 TTL。这样能缩短陈旧窗口，却会把所有请求都推向服务器，而且仍然无法保证变更发生后立刻生效。真正需要先确认的是：

• 缓存的是 tools/list、resources/list，还是具体 URI 的 resources/read；
• 列表是否经过权限过滤，不同令牌看到的集合是否相同；
• 服务器是否声明 listChanged 或资源订阅能力；
• 客户端是否真的打开了 subscriptions/listen 并请求对应通知；
• 分页结果是否被当成一个整体缓存，游标失效后是否从首页重建。

当前 MCP 2026-07-28 规范已经把缓存提示写进协议。tools/list、resources/list、resources/templates/list 和 resources/read 的完整结果都带有 ttlMs 与 cacheScope。因此客户端不必再为所有服务器猜一个统一时长。

先拆成三类缓存

缓存键不能只用服务器地址。规范要求方法和影响结果的请求参数共同识别缓存响应：resources/read 至少要包含 URI，分页列表要包含 cursor。对 private 结果，还要把授权上下文纳入分区；不同访问令牌或不同主体之间不能共享。

工具列表也可能随请求所带授权而变化。一个用户只看到只读工具，另一个用户能看到写入工具，这种列表就不能标成 public。服务器即使位于认证端点，只要发出 public，缓存层就可能把结果共享给其他调用方，所以范围配置必须比“有没有登录”更谨慎。

ttlMs 是新鲜度提示，不是轮询闹钟

ttlMs 表示客户端在多长时间内可以把结果视为新鲜。值为 0 时立即陈旧；正值表示从接收响应那一刻起计算的新鲜窗口。它不是服务器承诺“期间绝不会变化”，也不应该直接变成固定后台轮询间隔。

更合适的客户端行为是惰性重取：用到某个条目时先检查本地接收时间加 ttlMs，仍新鲜就复用，已过期才向服务器请求。若确实需要主动轮询，应增加抖动和退避，避免大量客户端同时刷新。

我通常把 TTL 看成通知机制的兜底，而不是替代品。稳定、所有用户一致的工具目录可以有较长 TTL；权限过滤的资源目录使用 private 分区；频繁变化的资源正文则给较短 TTL，并尽量订阅指定 URI。这样既减少请求，也把陈旧窗口限制在可解释范围内。

通知只负责失效，重新拉取负责恢复

在 2026-07-28 规范中，服务器声明工具或资源的 listChanged 能力后，客户端仍需打开 subscriptions/listen，并在通知过滤条件中选择 toolsListChanged 或 resourcesListChanged。指定资源内容更新则通过 resourceSubscriptions 列出 URI，服务器在对应流上发送 notifications/resources/updated。

这些通知应被当作“缓存已经不可信”的电铃，而不是新数据本身。收到工具列表变化通知时，将该服务器与授权分区下的 tools/list 分页全部标记陈旧；收到资源列表变化通知时，对资源目录执行同样处理；收到指定 URI 的更新通知时，只失效该 URI 对应的 resources/read 条目。真正的新描述、新 schema 或新正文仍从下一次 list/read 响应取得。

通知负责缩短陈旧窗口，TTL 负责通知缺失时的最终恢复；两者同时使用，不能互相替代。

分页缓存最容易留下半新半旧的视图

MCP 允许列表分页，每一页都是独立可缓存响应，也有自己的 ttlMs。这意味着第一页可能仍新鲜，末页已经过期。规范不提供跨页一致性保证，底层集合在翻页期间变化时，客户端可能看到重复项或缺口。

如果只是给用户做渐进式浏览，可以按页刷新；如果要把完整工具集合送进模型上下文，我更倾向于把一次完整遍历视为同一代快照。只要发生以下任一情况，就丢弃该列表的所有缓存页并从无 cursor 的第一页重新获取：

• 收到相应的 list_changed 通知；
• 此前有效的 cursor 被服务器拒绝；
• 关键工具调用返回“方法不存在”或参数 schema 明显不匹配；
• 客户端需要一个一致的完整集合，而分页期间检测到底层目录变化。

同一个分页列表的各页必须使用相同 cacheScope。如果第一页是 private，后续页也必须是 private；客户端不要因为某一页看起来不含敏感字段，就把它单独提升为共享缓存。

断线和旧服务端要有退路

并非所有服务端都会声明变更能力，也不是每条通知流都能永久保持。未提供通知时，完全依赖 TTL 是规范允许的；监听流异常关闭后，客户端应重建监听，并保留 TTL 到期后的按需刷新。重新连接期间可以在短时故障下服务旧缓存，但要明确标记为 stale，并避免把旧 schema 当成不可疑的调用依据。

协议版本也要进入兼容策略。2026-07-28 使用 subscriptions/listen 选择通知类型；较早实现可能仍采用旧订阅机制。客户端应根据协商或请求元数据识别版本，不要把新版通知假设硬套到旧服务端，也不要因为旧服务端没有新版字段就永久缓存结果。缺少 ttlMs 时，当前规范建议按 0 处理，也就是默认立即陈旧。

我最后采用的缓存规则

1. 缓存键由服务器身份、方法、所有影响结果的参数和授权分区组成。
2. public 仅用于所有调用方完全一致的结果；其他情况一律按 private 分区。
3. TTL 到期时按需重取，不把 TTL 直接当轮询周期。
4. 通知到达时立即标陈旧，但把批量重取合并到一次去抖任务，避免变更风暴。
5. 列表通知清除该列表的全部分页；资源更新只清除目标 URI 的读取结果。
6. 模型每次生成前使用同一代工具目录，避免一轮推理中途替换 schema。
7. 工具调用出现不存在或参数无效时，允许在 TTL 内提前刷新一次描述，再决定是否重试。

这套策略的代价是缓存实现不再只有一个 map，但收益很直观：工具描述变化能快速生效，资源正文更新不会误伤整个目录缓存，权限隔离也更清楚。对只接一个静态 MCP 服务的小客户端，完整实现可能偏重；对聚合多个服务、多人共享网关或把工具清单长期放进模型上下文的系统，这些边界很值得提前做。

复查时看哪些指标

• 按方法命中率：分开观察 tools/list、resources/list 和 resources/read，不要只看总命中率。
• 通知到失效延迟：收到通知后多久把条目标为陈旧，是否有跨进程广播遗漏。
• 陈旧命中次数：在重取失败时服务了多少 stale 结果，持续时间多长。
• 强制整表重建次数：分页 cursor 失效、工具不存在或 schema 不匹配是否频繁发生。
• 权限分区数量：防止授权主体过多导致缓存无限膨胀，同时不能合并不同权限上下文。
• 通知风暴合并率：短时间内多次变更是否只触发一次实际重取。

常见问题

有 list_changed 通知后，还需要 ttlMs 吗？

需要。通知可能因为客户端离线、监听流中断或服务端未实现而缺失，TTL 是最终恢复机制；反过来，通知能在 TTL 未到期时立即使缓存陈旧。

工具 description 只是文案，为什么要及时更新？

工具描述、输入 schema 和注解都会影响模型选择工具与构造参数。继续使用旧列表，可能让模型调用已删除工具，或按旧字段发送请求，因此它属于运行契约的一部分。

resources/list 变化是否意味着所有资源正文都要清空？

不必机械清空。列表变化说明目录集合需要重新获取；具体资源正文应按 URI 的更新通知或自身 TTL 失效。若 URI 被删除，再移除对应正文缓存即可。

可以把 tools/list 标成 public 吗？

只有在所有授权上下文看到完全相同工具集合和描述时才合适。只要工具会按用户、租户或 scope 过滤，就应使用 private，并按授权上下文隔离。

官方资料

• MCP Tools 规范：https://modelcontextprotocol.io/specification/2026-07-28/server/tools
• MCP Resources 规范：https://modelcontextprotocol.io/specification/2026-07-28/server/resources
• MCP Caching 规范：https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/caching
• 2026-07-28 版本说明：https://blog.modelcontextprotocol.io/posts/2026-07-28/