MCP Server新增工具后客户端一直看不到？ttlMs、cacheScope与listChanged缓存排查

文章摘要

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动态返回的工具。

错误配置：

不同租户工具不同 但cacheScope=public

可能导致工具存在性泄露，甚至让模型尝试调用无权工具。

五、缓存键必须包含什么

错误缓存键：

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(List<ToolDefinition>tools,InstantcachedAt,InstantexpiresAt,StringcacheScope){publicbooleanexpired(Clockclock){returnclock.instant().isAfter(expiresAt);}}

读取：

publicList<ToolDefinition>getTools(ToolListCacheKeykey){CachedToolListcached=cache.get(key);if(cached!=null&&!cached.expired(clock)){returncached.tools();}ToolListResultremote=mcpClient.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 ＋多实例失效 ＋执行阶段重新授权

尤其要记住：工具列表可以缓存，工具权限不能缓存为永久信任。