文章摘要MCP 2026-07-28为工具、资源和Prompt列表增加了缓存语义。客户端可以根据ttlMs缓存tools/list结果并根据cacheScope决定是否允许共享。新机制能够减少频繁列表请求但也带来新问题服务端新增工具后客户端长期不可见、权限撤销后旧工具仍显示、不同租户获得错误工具列表。本文给出缓存键、TTL、listChanged通知、权限隔离和灰度更新的完整排查方法。一、典型现象服务端新增order_refund服务端日志显示工具已经注册。直接调用服务端tools/list也能看到。但业务Agent仍然只看到旧工具order_query order_cancel重启客户端后新工具突然出现。这通常说明客户端工具列表缓存没有失效二、为什么要缓存工具列表大型MCP Server可能暴露数百个工具。如果每次模型请求前都执行tools/list会造成网络请求增加JSON Schema传输成本服务端动态计算压力客户端启动变慢多个Agent重复发现工具网关日志膨胀。因此新规范允许列表响应提供缓存提示。三、ttlMs表示什么示意{tools:[],ttlMs:300000,cacheScope:private}300000毫秒等于5分钟。客户端可以在5分钟内继续使用当前列表不必重新调用。注意ttlMs是缓存新鲜度提示 不是服务端保证工具五分钟内绝不变化如果工具权限发生紧急撤销不能只等待TTL自然过期。四、cacheScope为什么重要public列表内容对不同用户相同可以在更大范围共享。适合公共天气工具公共计算工具不区分租户的只读能力。private列表与用户、租户或授权有关不应跨身份共享。适合订单工具财务工具管理员工具客户专属工具按Scope动态返回的工具。错误配置不同租户工具不同 但cacheScopepublic可能导致工具存在性泄露甚至让模型尝试调用无权工具。五、缓存键必须包含什么错误缓存键serverUrl所有用户共享同一列表。推荐缓存键至少包含server_identity protocol_version authorization_subject tenant_id scope_hash client_capabilities locale示例publicrecordToolListCacheKey(StringserverId,StringprotocolVersion,StringsubjectId,StringtenantId,StringscopeHash){}不要直接把完整Access Token放进缓存键和日志。六、listChanged通知的作用服务端工具列表发生变化时可以发送变化通知。客户端收到后立即标记缓存失效 → 下一次使用时重新调用tools/list理想流程工具发布 → Server发送listChanged → Client清除缓存 → Client重新发现如果使用Stateless服务端部分主动通知能力可能受限需要使用更短TTL发布事件总线配置版本号客户端定时刷新管理接口主动清除缓存。七、新工具不可见的排查顺序第一步服务端原始列表绕过业务客户端直接确认tools/list是否包含新工具如果没有问题在服务端注册。第二步检查响应缓存字段记录ttlMs cacheScope listVersion第三步检查客户端缓存命中cache_key cache_hit cached_at expires_at第四步检查listChanged服务端是否发送 网关是否允许 客户端是否注册处理器 处理后是否真正删除缓存第五步检查工具过滤重新获取列表后新工具也可能被过滤。八、旧权限撤销后工具仍显示更危险新工具暂时不可见只是可用性问题。已经撤销权限的工具仍留在缓存中则是安全问题。例如用户原有refund:order → 权限被撤销 → 客户端仍显示order_refund即使最终调用会被服务端拒绝也会暴露工具存在误导模型计划增加失败调用泄露参数Schema造成用户困惑。权限变化应主动使缓存失效。九、工具列表与执行权限必须双重校验不能因为工具出现在列表中就认为执行一定允许。工具调用时仍必须检查当前Token 当前Scope 当前租户 当前用户 当前资源归属 当前风险策略列表是发现机制不是最终授权。十、动态工具列表如何设计部分企业工具按角色动态返回普通用户 → query_order 客服主管 → query_order、cancel_order 财务人员 → refund_order服务端生成列表时应该基于认证上下文。但动态程度越高缓存越复杂。建议工具定义总体稳定 调用权限在执行阶段校验对于极高敏感工具可以在列表阶段隐藏。十一、使用版本号简化失效可以维护tool_catalog_version例如2026.07.30.3缓存记录{serverId:order-mcp,catalogVersion:2026.07.30.3,expiresAt:...}发布后版本变化客户端可以快速判断失效。版本号不是协议强制字段时可以通过服务元数据管理API配置中心自定义响应元数据事件总线实现。十二、合理TTL怎么设置静态公共工具30分钟到数小时普通企业工具5到15分钟权限频繁变化1分钟以内 主动失效高风险工具可以短TTL 执行时强校验 审批TTL越短实时性越好但服务端压力更高。十三、多实例客户端缓存一致性客户端应用有10个实例实例1收到listChanged 实例2—10没有收到工具列表会不一致。推荐共享失效通道Redis Pub/Sub Kafka Spring Cloud Bus 配置中心版本处理任一实例发现变化 → 发布ToolCatalogChangedEvent → 全部实例清除对应缓存十四、灰度发布新工具新工具不应一次性对所有模型开放。可以按租户 用户组 客户端版本 模型版本 环境灰度。缓存键必须包含灰度维度否则测试用户获取新工具 → 缓存被普通用户共享十五、缓存实现示例publicrecordCachedToolList(ListToolDefinitiontools,InstantcachedAt,InstantexpiresAt,StringcacheScope){publicbooleanexpired(Clockclock){returnclock.instant().isAfter(expiresAt);}}读取publicListToolDefinitiongetTools(ToolListCacheKeykey){CachedToolListcachedcache.get(key);if(cached!null!cached.expired(clock)){returncached.tools();}ToolListResultremotemcpClient.listTools();cache.put(key,fromRemote(remote));returnremote.tools();}十六、监控指标mcp_tool_list_request_count mcp_tool_list_cache_hit_rate mcp_tool_list_cache_miss_rate mcp_tool_list_refresh_failure mcp_tool_list_changed_event_count mcp_tool_catalog_version mcp_stale_tool_call_count mcp_unauthorized_cached_tool_count重点告警权限撤销后仍有旧工具调用十七、排查清单□ 服务端tools/list包含新工具 □ 客户端是否命中旧缓存 □ ttlMs是否过长 □ cacheScope是否正确 □ 缓存键是否包含用户与租户 □ listChanged是否发送和处理 □ 多实例是否同步失效 □ 工具过滤是否排除新工具 □ 权限变化是否触发失效 □ 执行阶段是否再次鉴权总结MCP工具列表缓存解决了重复发现成本但也把工具治理从一次请求变成了缓存一致性问题。生产系统必须同时处理ttlMs cacheScope 精确缓存键 listChanged 多实例失效 执行阶段重新授权尤其要记住工具列表可以缓存工具权限不能缓存为永久信任。
