文章摘要MCP 2026-07-28為工具、資源和Prompt列表增加了緩存語義?？蛻舳丝梢愿鶕?jù)ttlMs緩存tools/list結(jié)果并根據(jù)cacheScope決定是否允許共享。新機(jī)制能夠減少頻繁列表請求但也帶來新問題服務(wù)端新增工具后客戶端長期不可見、權(quán)限撤銷后舊工具仍顯示、不同租戶獲得錯誤工具列表。本文給出緩存鍵、TTL、listChanged通知、權(quán)限隔離和灰度更新的完整排查方法。一、典型現(xiàn)象服務(wù)端新增order_refund服務(wù)端日志顯示工具已經(jīng)注冊。直接調(diào)用服務(wù)端tools/list也能看到。但業(yè)務(wù)Agent仍然只看到舊工具order_query order_cancel重啟客戶端后新工具突然出現(xiàn)。這通常說明客戶端工具列表緩存沒有失效二、為什么要緩存工具列表大型MCP Server可能暴露數(shù)百個工具。如果每次模型請求前都執(zhí)行tools/list會造成網(wǎng)絡(luò)請求增加JSON Schema傳輸成本服務(wù)端動態(tài)計算壓力客戶端啟動變慢多個Agent重復(fù)發(fā)現(xiàn)工具網(wǎng)關(guān)日志膨脹。因此新規(guī)范允許列表響應(yīng)提供緩存提示。三、ttlMs表示什么示意{tools:[],ttlMs:300000,cacheScope:private}300000毫秒等于5分鐘?？蛻舳丝梢栽?分鐘內(nèi)繼續(xù)使用當(dāng)前列表不必重新調(diào)用。注意ttlMs是緩存新鮮度提示 不是服務(wù)端保證工具五分鐘內(nèi)絕不變化如果工具權(quán)限發(fā)生緊急撤銷不能只等待TTL自然過期。四、cacheScope為什么重要public列表內(nèi)容對不同用戶相同可以在更大范圍共享。適合公共天氣工具公共計算工具不區(qū)分租戶的只讀能力。private列表與用戶、租戶或授權(quán)有關(guān)不應(yīng)跨身份共享。適合訂單工具財務(wù)工具管理員工具客戶專屬工具按Scope動態(tài)返回的工具。錯誤配置不同租戶工具不同 但cacheScopepublic可能導(dǎo)致工具存在性泄露甚至讓模型嘗試調(diào)用無權(quán)工具。五、緩存鍵必須包含什么錯誤緩存鍵serverUrl所有用戶共享同一列表。推薦緩存鍵至少包含server_identity protocol_version authorization_subject tenant_id scope_hash client_capabilities locale示例publicrecordToolListCacheKey(StringserverId,StringprotocolVersion,StringsubjectId,StringtenantId,StringscopeHash){}不要直接把完整Access Token放進(jìn)緩存鍵和日志。六、listChanged通知的作用服務(wù)端工具列表發(fā)生變化時可以發(fā)送變化通知?？蛻舳耸盏胶罅⒓礃?biāo)記緩存失效 → 下一次使用時重新調(diào)用tools/list理想流程工具發(fā)布 → Server發(fā)送listChanged → Client清除緩存 → Client重新發(fā)現(xiàn)如果使用Stateless服務(wù)端部分主動通知能力可能受限需要使用更短TTL發(fā)布事件總線配置版本號客戶端定時刷新管理接口主動清除緩存。七、新工具不可見的排查順序第一步服務(wù)端原始列表繞過業(yè)務(wù)客戶端直接確認(rèn)tools/list是否包含新工具如果沒有問題在服務(wù)端注冊。第二步檢查響應(yīng)緩存字段記錄ttlMs cacheScope listVersion第三步檢查客戶端緩存命中cache_key cache_hit cached_at expires_at第四步檢查listChanged服務(wù)端是否發(fā)送 網(wǎng)關(guān)是否允許 客戶端是否注冊處理器 處理后是否真正刪除緩存第五步檢查工具過濾重新獲取列表后新工具也可能被過濾。八、舊權(quán)限撤銷后工具仍顯示更危險新工具暫時不可見只是可用性問題。已經(jīng)撤銷權(quán)限的工具仍留在緩存中則是安全問題。例如用戶原有refund:order → 權(quán)限被撤銷 → 客戶端仍顯示order_refund即使最終調(diào)用會被服務(wù)端拒絕也會暴露工具存在誤導(dǎo)模型計劃增加失敗調(diào)用泄露參數(shù)Schema造成用戶困惑。權(quán)限變化應(yīng)主動使緩存失效。九、工具列表與執(zhí)行權(quán)限必須雙重校驗不能因為工具出現(xiàn)在列表中就認(rèn)為執(zhí)行一定允許。工具調(diào)用時仍必須檢查當(dāng)前Token 當(dāng)前Scope 當(dāng)前租戶 當(dāng)前用戶 當(dāng)前資源歸屬 當(dāng)前風(fēng)險策略列表是發(fā)現(xiàn)機(jī)制不是最終授權(quán)。十、動態(tài)工具列表如何設(shè)計部分企業(yè)工具按角色動態(tài)返回普通用戶 → query_order 客服主管 → query_order、cancel_order 財務(wù)人員 → refund_order服務(wù)端生成列表時應(yīng)該基于認(rèn)證上下文。但動態(tài)程度越高緩存越復(fù)雜。建議工具定義總體穩(wěn)定 調(diào)用權(quán)限在執(zhí)行階段校驗對于極高敏感工具可以在列表階段隱藏。十一、使用版本號簡化失效可以維護(hù)tool_catalog_version例如2026.07.30.3緩存記錄{serverId:order-mcp,catalogVersion:2026.07.30.3,expiresAt:...}發(fā)布后版本變化客戶端可以快速判斷失效。版本號不是協(xié)議強(qiáng)制字段時可以通過服務(wù)元數(shù)據(jù)管理API配置中心自定義響應(yīng)元數(shù)據(jù)事件總線實現(xiàn)。十二、合理TTL怎么設(shè)置靜態(tài)公共工具30分鐘到數(shù)小時普通企業(yè)工具5到15分鐘權(quán)限頻繁變化1分鐘以內(nèi) 主動失效高風(fēng)險工具可以短TTL 執(zhí)行時強(qiáng)校驗 審批TTL越短實時性越好但服務(wù)端壓力更高。十三、多實例客戶端緩存一致性客戶端應(yīng)用有10個實例實例1收到listChanged 實例2—10沒有收到工具列表會不一致。推薦共享失效通道Redis Pub/Sub Kafka Spring Cloud Bus 配置中心版本處理任一實例發(fā)現(xiàn)變化 → 發(fā)布ToolCatalogChangedEvent → 全部實例清除對應(yīng)緩存十四、灰度發(fā)布新工具新工具不應(yīng)一次性對所有模型開放。可以按租戶 用戶組 客戶端版本 模型版本 環(huán)境灰度。緩存鍵必須包含灰度維度否則測試用戶獲取新工具 → 緩存被普通用戶共享十五、緩存實現(xiàn)示例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();}十六、監(jiān)控指標(biāo)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重點告警權(quán)限撤銷后仍有舊工具調(diào)用十七、排查清單□ 服務(wù)端tools/list包含新工具 □ 客戶端是否命中舊緩存 □ ttlMs是否過長 □ cacheScope是否正確 □ 緩存鍵是否包含用戶與租戶 □ listChanged是否發(fā)送和處理 □ 多實例是否同步失效 □ 工具過濾是否排除新工具 □ 權(quán)限變化是否觸發(fā)失效 □ 執(zhí)行階段是否再次鑒權(quán)總結(jié)MCP工具列表緩存解決了重復(fù)發(fā)現(xiàn)成本但也把工具治理從一次請求變成了緩存一致性問題。生產(chǎn)系統(tǒng)必須同時處理ttlMs cacheScope 精確緩存鍵 listChanged 多實例失效 執(zhí)行階段重新授權(quán)尤其要記住工具列表可以緩存工具權(quán)限不能緩存為永久信任。