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
示例：
public record ToolListCacheKey(
String serverId,
String protocolVersion,
String subjectId,
String tenantId,
String scopeHash
) {
}
不要直接把完整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
→ 全部实例清除对应缓存
十四、灰度发布新工具
新工具不应一次性对所有模型开放。
可以按：
租户
用户组
客户端版本
模型版本
环境
灰度。
缓存键必须包含灰度维度，否则：
测试用户获取新工具
→ 缓存被普通用户共享
十五、缓存实现示例
public record CachedToolList(
List tools,
Instant cachedAt,
Instant expiresAt,
String cacheScope
) {
public boolean expired(Clock clock) {
return clock.instant().isAfter(expiresAt);
}
}
读取：
public List getTools(
ToolListCacheKey key
) {
CachedToolList cached = cache.get(key);
if (cached != null && !cached.expired(clock)) {
return cached.tools();
}
ToolListResult remote = mcpClient.listTools();
cache.put(key, fromRemote(remote));
return remote.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
＋多实例失效
＋执行阶段重新授权
尤其要记住：工具列表可以缓存，工具权限不能缓存为永久信任。
延伸阅读
如果你正在关注企业级 AI 应用、Spring AI、RAG、Agent 与 MCP 工程化落地，欢迎访问 智元界：
https://www.zyentor.com/
智元界将持续分享可运行的技术实战、架构设计、问题排查与企业应用案例。