文章摘要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 多實例失效 執行階段重新授權尤其要記住工具列表可以緩存工具權限不能緩存為永久信任。