FastMCP ClientGroup 詳解多服務(wù)器客戶端編排、工具命名空間與獨(dú)立協(xié)議協(xié)商【免費(fèi)下載鏈接】fastmcp The fast, Pythonic way to build MCP servers and clients.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp導(dǎo)讀ClientGroup是 FastMCP v4.0 引入的客戶端編排原語(yǔ)用于協(xié)調(diào)多個(gè)彼此獨(dú)立的 FastMCP 客戶端每個(gè)客戶端保留自己獨(dú)立的連接、協(xié)商出的協(xié)議版本與能力工具以{server}_{tool}的命名空間形式統(tǒng)一發(fā)布調(diào)用則路由回最初發(fā)布該工具的那個(gè)客戶端。讀完本文你將掌握如何把多個(gè)協(xié)議時(shí)代如legacy與auto的 MCP 服務(wù)器喂給同一個(gè) Agent、如何為單臺(tái)服務(wù)器單獨(dú)實(shí)現(xiàn)工具前綴命名空間、如何通過(guò)resolve_tool()將工具綁定到其所屬連接以及ClientGroup在并發(fā)、故障隔離與緩存刷新上的行為邊界。本文以 dev-docs/v4-notes/client-groups.md 這份 v4 設(shè)計(jì)筆記為主體結(jié)合 docs/clients/client-groups.mdx 用戶文檔、group.py 實(shí)現(xiàn)與 test_client_group.py 測(cè)試展開(kāi)。背景為什么需要一個(gè)介于兩者之間的編排對(duì)象在ClientGroup出現(xiàn)之前把來(lái)自多個(gè)服務(wù)器的工具交給同一個(gè) Agent只能在兩種都有明顯缺陷的形態(tài)中二選一見(jiàn) dev-docs/v4-notes/client-groups.md單一Client(config)聚合多服務(wù)器配置被組合在一個(gè)進(jìn)程內(nèi)代理后面所有后端共享同一個(gè)協(xié)商出的協(xié)議時(shí)代。一個(gè)走握手時(shí)代handshake era的后端會(huì)把所有現(xiàn)代后端都拉回握手時(shí)代重連并發(fā)調(diào)用則全部經(jīng)由同一個(gè)前端會(huì)話串行化。每服務(wù)器一個(gè)Client每個(gè)連接都能保住自己協(xié)商出的協(xié)議時(shí)代但沒(méi)有任何對(duì)象負(fù)責(zé)組合——調(diào)用方必須手寫(xiě)命名空間、碰撞檢測(cè)、生命周期和路由邏輯。ClientGroup正是填補(bǔ)這兩者之間空白的對(duì)象一個(gè)名稱(chēng) → 客戶端的映射其中每個(gè)連接獨(dú)立協(xié)商協(xié)議工具以{server}_{tool}發(fā)布調(diào)用路由回發(fā)布該工具的客戶端。它位于fastmcp.client.group被放在主命名空間下因?yàn)槠鋵?duì)外表面積是純?cè)隽康摹ＴO(shè)計(jì)筆記點(diǎn)明了直接的驅(qū)動(dòng)因素——按服務(wù)器釘定協(xié)議per-server protocol pinningAgent 集成需要在某臺(tái)服務(wù)器上用modelegacy在另一臺(tái)上用modeauto這是單一聚合連接無(wú)法表達(dá)的。與此同時(shí)命名空間訴求為單臺(tái)服務(wù)器的工具加前綴也在持續(xù)出現(xiàn)因?yàn)橥慌梢讯嗯_(tái)服務(wù)器的工具喂給同一個(gè)模型。測(cè)試 test_client_group.py 中的test_clients_negotiate_independently直觀印證了這一點(diǎn)同一組內(nèi)舊客戶端協(xié)商出2025-11-25、新客戶端協(xié)商出2026-07-28兩個(gè)協(xié)議時(shí)代并存且各自獨(dú)立工作?？焖偕鲜謴目蛻舳藰?gòu)建一個(gè) ClientGroup當(dāng)每臺(tái)服務(wù)器需要各自的 handler、認(rèn)證或連接設(shè)置時(shí)顯式構(gòu)造客戶端再組成 groupfrom pathlib import Path import asyncio from fastmcp import Client from fastmcp.client.group import ClientGroup legacy_client Client(Path(legacy_server.py), modelegacy) modern_client Client(https://modern.example.com/mcp, modeauto) group ClientGroup( { legacy: legacy_client, modern: modern_client, } ) async def main() - None: async with group: tools await group.list_tools() print([tool.name for tool in tools]) result await group.call_tool( modern_get_weather, {city: Chicago}, ) print(result) asyncio.run(main())工具名默認(rèn)以配置的客戶端名作為前綴。例如modern客戶端暴露的get_weather工具在 group 層面變成modern_get_weather。單客戶端 group 是合法的命名空間方案只包含一個(gè)客戶端的 group會(huì)把該服務(wù)器的工具統(tǒng)一掛到其配置名稱(chēng)下行為上沒(méi)有任何其他變化。測(cè)試 test_single_client_group_provides_namespacing_alone.py 驗(yàn)證了solo_echo、solo_protocol_era這樣的命名空間產(chǎn)物。懶加載目錄首次路由調(diào)用才會(huì)懶加載工具目錄cold start。加載成功后未知工具名會(huì)在本地失敗而不會(huì)對(duì)每臺(tái)服務(wù)器重復(fù)做一次發(fā)現(xiàn)。當(dāng)服務(wù)器動(dòng)態(tài)增刪工具時(shí)顯式調(diào)用list_tools()可以刷新路由——這個(gè)顯式調(diào)用會(huì)繞過(guò)任何客戶端側(cè)響應(yīng)緩存讓目錄反映每臺(tái)服務(wù)器現(xiàn)在實(shí)際發(fā)布的內(nèi)容。工具命名空間與碰撞檢測(cè)的實(shí)現(xiàn)命名空間與碰撞檢測(cè)不是靠字符串拼接那么簡(jiǎn)單。在 group.py 的list_tools()中并行地對(duì)每個(gè)客戶端調(diào)用client.list_tools()通過(guò)utilities.async_utils.gather每個(gè)工具生成公開(kāi)名{server_name}_{tool.name}并用tool.model_copy(update{name: public_name})產(chǎn)生重命名后的副本若同一公開(kāi)名被兩臺(tái)服務(wù)器同時(shí)命中例如服務(wù)器名a的工具b_echo與服務(wù)器名a_b的工具echo都變成a_b_echo直接拋出ValueError: Tool name collision: a_b_echo同時(shí)構(gòu)建并緩存一張public_name - ToolRoute路由表。ToolRoute是一個(gè) frozen dataclassgroup.py攜帶三個(gè)字段server_name組內(nèi)的服務(wù)器名、client發(fā)布該工具的客戶端實(shí)例、upstream_name服務(wù)器自己聲明的原始工具名。碰撞檢測(cè)之所以放在組合層而非Client層是因?yàn)榍熬Y本質(zhì)上是碰撞策略而碰撞策略理應(yīng)屬于負(fù)責(zé)檢測(cè)碰撞的組合對(duì)象。resolve_tool()把工具綁定回它的所屬連接工具適配器把 MCP 工具轉(zhuǎn)成 Agent 框架可調(diào)用對(duì)象的那層代碼往往需要的不僅僅是路由調(diào)用——會(huì)話驅(qū)動(dòng)的輸入循環(huán)、handler 上下文、攔截器都必須跑在真正擁有該工具的連接上。resolve_tool()返回的就是這條完整路由因此適配器可以經(jīng)由 group 做發(fā)現(xiàn)再把每個(gè)生成的工具綁定到其真實(shí)客戶端async with group: for tool in await group.list_tools(): route await group.resolve_tool(tool.name) # route.client 是持有該工具的已連接 FastMCP 客戶端 # route.upstream_name 是服務(wù)器自己聲明的原始工具名 register_agent_tool(tool, clientroute.client, nameroute.upstream_name)這正是無(wú)合成前端No synthetic frontend設(shè)計(jì)決策的落點(diǎn)group 只負(fù)責(zé)聚合名稱(chēng)與檢測(cè)碰撞從不站在適配器與客戶端之間。沒(méi)有聚合會(huì)話、沒(méi)有協(xié)議翻譯因此單個(gè)Client支持的一切認(rèn)證、tracing、緩存、結(jié)果解析、進(jìn)度、多輪工具對(duì)每個(gè)工具都繼續(xù)有效。resolve_tool()的路由解析語(yǔ)義group.py值得注意已知路由只要求自己的客戶端已連接——一臺(tái)死掉的服務(wù)器不會(huì)把故障耦合到路由向健康服務(wù)器的調(diào)用上。測(cè)試 test_known_route_survives_an_unrelated_dead_client 展示了doomed客戶端斷開(kāi)后healthy_echo照?？烧{(diào)而doomed_echo拋出RuntimeError。目錄加載仍要求全員在線——首次解析或刷新后要查詢所有客戶端。懶加載在anyio.Lock保護(hù)下進(jìn)行多路并發(fā)冷啟動(dòng)調(diào)用共享同一次發(fā)現(xiàn)測(cè)試 test_concurrent_cold_calls_share_tool_discovery 斷言list_tools每臺(tái)服務(wù)器只被調(diào)用一次未知工具也不會(huì)重復(fù)觸發(fā)發(fā)現(xiàn)見(jiàn) test_unknown_tools_do_not_repeat_discovery。from_config每服務(wù)器獨(dú)立協(xié)商協(xié)議的配置入口ClientGroup.from_config為配置中的每臺(tái)服務(wù)器各創(chuàng)建一個(gè)客戶端而不是把整個(gè)配置塞進(jìn)一個(gè)代理。FastMCP 特有的mode字段可以為每臺(tái)服務(wù)器單獨(dú)選擇協(xié)議行為group.pyfrom fastmcp.client.group import ClientGroup config { mcpServers: { legacy: { command: python, args: [legacy_server.py], mode: legacy, }, modern: { url: https://modern.example.com/mcp, mode: auto, }, } } group ClientGroup.from_config(config)未帶mode的條目默認(rèn)使用autodefault_mode參數(shù)類(lèi)型為ConnectMode Literal[legacy, auto] | str定義見(jiàn) client.py。從實(shí)現(xiàn)看mode通過(guò)server.model_extra讀取——它是 MCP 配置 schema 之外的 FastMCP 擴(kuò)展字段若值不是字符串from_config會(huì)拋出TypeError。每個(gè)客戶端以Client(server.to_transport(), modeconfigured_mode)構(gòu)造mode只作用于該服務(wù)器。測(cè)試 test_from_config_applies_mode_per_server 驗(yàn)證了同一配置里legacy與auto各自生效protocol_versions分別為2025-11-25與2026-07-28。連接生命周期上下文管理器、并發(fā)進(jìn)入與引用計(jì)數(shù)兩種使用方式用 group 作為上下文管理器是可選的。應(yīng)用可以自行持有每個(gè)客戶端連接只把 group 當(dāng)作發(fā)現(xiàn)與路由工具async with legacy_client, modern_client: tools await group.list_tools()也可以在客戶端上下文內(nèi)部進(jìn)入 group。FastMCP 客戶端上下文是引用計(jì)數(shù)的client.py 注釋明確說(shuō)明首次調(diào)用創(chuàng)建后臺(tái)會(huì)話任務(wù)并等待就緒后續(xù)調(diào)用遞增引用計(jì)數(shù)并復(fù)用既有會(huì)話所以退出 group 不會(huì)關(guān)閉仍由外層上下文持有的連接。測(cè)試 test_group_context_does_not_close_caller_owned_client 驗(yàn)證了這一點(diǎn)。并發(fā)進(jìn)入與部分失敗回滾__aenter__group.py的實(shí)現(xiàn)體現(xiàn)了幾條關(guān)鍵不變式進(jìn)入守衛(wèi)在第一個(gè)await之前就先把AsyncExitStack掛到self._exit_stack上讓并發(fā)的第二次進(jìn)入命中RuntimeError(ClientGroup is already connected)守衛(wèi)而不是競(jìng)態(tài)覆蓋測(cè)試 test_concurrent_group_entry_does_not_double_connect。并發(fā)連接所有客戶端同時(shí)__aenter__因此進(jìn)入延遲大致保持一次握手深度而不是隨服務(wù)器數(shù)量線性增長(zhǎng)。return_exceptionsTrue保證每個(gè)連接嘗試都跑完從而知道哪些成功、可以精確回滾。部分失敗回滾任一客戶端連接失敗時(shí)已成功連接的客戶端會(huì)被依次__aexit__清理?xiàng)１魂P(guān)閉然后拋出第一個(gè)錯(cuò)誤測(cè)試 test_partial_connect_failure_unwinds_connected_clients。每服務(wù)器一條連接組內(nèi)成員共享客戶端實(shí)例一臺(tái)服務(wù)器的 lifespan 只進(jìn)入一次測(cè)試 test_group_keeps_one_connection_per_server 斷言entered 1。group 自身不新增任何會(huì)話處理。每個(gè)客戶端像獨(dú)立使用時(shí)一樣持有自己的傳輸與會(huì)話因此一個(gè) legacy 有狀態(tài)會(huì)話例如經(jīng) SSE 或 stdio只要其客戶端上下文存活就一直保持打開(kāi)無(wú)論進(jìn)入它的是 group 還是調(diào)用方。成員不可變clients屬性返回MappingProxyType只讀映射構(gòu)造后成員不可變group.py——因?yàn)槁酚杀沓钟邪l(fā)布工具的客戶端引用若映射被替換路由會(huì)悄悄失效。測(cè)試 test_client_membership_is_immutable 斷言向group.clients賦值會(huì)拋TypeError。目錄刷新與緩存語(yǔ)義list_tools()默認(rèn)cache_moderefresh顯式調(diào)用就是 group 的目錄刷新機(jī)制客戶端側(cè)響應(yīng)緩存SEP-2549會(huì)被重新填充而非命中路由反映的是每臺(tái)服務(wù)器現(xiàn)在發(fā)布的內(nèi)容。測(cè)試 test_explicit_list_tools_refreshes_past_client_response_cache 展示在帶cache_ttl提示的服務(wù)器上顯式list_tools()能發(fā)現(xiàn)動(dòng)態(tài)新增的hinted_added工具并可立即調(diào)用。相對(duì)地懶加載的冷啟動(dòng)發(fā)現(xiàn)resolve_tool首次解析會(huì)以cache_modeuse執(zhí)行允許命中緩存——只有顯式list_tools()才承諾刷新后的目錄。若需要容忍服務(wù)器提示范圍內(nèi)的短暫陳舊也可以顯式傳cache_modeuse。設(shè)計(jì)決策四個(gè)關(guān)鍵取舍設(shè)計(jì)筆記用四條決策劃定了ClientGroup的邊界用 Group 而不是 kwarg。一個(gè)tool_name_prefixkwarg 曾被完整實(shí)現(xiàn)作為對(duì)照方案#4932已關(guān)閉并最終被拒絕前綴本質(zhì)上是碰撞策略而碰撞策略應(yīng)歸屬負(fù)責(zé)檢測(cè)碰撞的組合對(duì)象同時(shí)它會(huì)讓穩(wěn)定的單服務(wù)器客戶端對(duì)外暴露服務(wù)器從未聲明的名字。group 的字典鍵本身就是命名空間——單客戶端 group 是單獨(dú)獲得命名空間的受支持方式正是這一決策的推論。無(wú)合成前端。沒(méi)有聚合會(huì)話、沒(méi)有協(xié)議翻譯。resolve_tool()返回服務(wù)器名、所屬Client與上游工具名因?yàn)楣ぞ哌m配器需要把按工具綁定的行為會(huì)話驅(qū)動(dòng)的輸入循環(huán)、handler、攔截器掛到真實(shí)連接上group 從不站在適配器與客戶端之間。不變式優(yōu)先于靈活性。成員構(gòu)造后不可變路由持有廣告客戶端突變會(huì)使路由失效組進(jìn)入有競(jìng)態(tài)保護(hù)且并發(fā)連接部分失敗時(shí)回滾已成功的連接已知路由只要求自己的客戶端在線一臺(tái)死服務(wù)器不會(huì)拖垮路由向健康服務(wù)器的調(diào)用只有目錄發(fā)現(xiàn)這種查詢所有人的操作才要求全艦隊(duì)在線。當(dāng)前僅限工具Tool-only。資源resource采用基于 URI 的身份碰撞規(guī)則不同提示prompt調(diào)用面也不同。擴(kuò)展到工具之外應(yīng)遵循具體使用需求而不是按類(lèi)比提前宣告策略。性能特征設(shè)計(jì)筆記給出了對(duì)兩臺(tái)真實(shí)本地 streamable-HTTP 服務(wù)器實(shí)測(cè)的結(jié)論比值比絕對(duì)值更可信路由調(diào)用與直連調(diào)用不可區(qū)分p50 均為 1.89ms而Client(config)代理每次調(diào)用額外增加約 65% 開(kāi)銷(xiāo)。并發(fā)下差距被放大跨兩臺(tái)服務(wù)器 200 個(gè)并發(fā)調(diào)用經(jīng)由 group 約 145ms經(jīng)由代理約 875ms快約 6 倍——因?yàn)?group 在獨(dú)立會(huì)話間扇出而代理通過(guò)單一會(huì)話串行化。組進(jìn)入延遲客戶端并發(fā)連接進(jìn)入延遲大致保持一次握手深度不隨服務(wù)器數(shù)量線性增長(zhǎng)。需要說(shuō)明的是這些是設(shè)計(jì)筆記作者針對(duì)特定環(huán)境的測(cè)量結(jié)果用于說(shuō)明比值這一結(jié)論實(shí)際數(shù)字會(huì)隨服務(wù)器實(shí)現(xiàn)與運(yùn)行環(huán)境變化。與 MCP Python SDK 的 ClientSessionGroup 的關(guān)系MCP Python SDK 的ClientSessionGroup是同類(lèi)先例prior art兩者的分工值得分清用戶文檔 docs/clients/client-groups.mdx 的Related: SDK session groups一節(jié)亦有說(shuō)明SDK 的connect_to_server()擁有生命周期但只講經(jīng)典握手協(xié)議connect_with_session()可以注冊(cè)一個(gè)外部協(xié)商好的現(xiàn)代會(huì)話但不擁有它。ClientGroup則把獨(dú)立的現(xiàn)代協(xié)議協(xié)商與組擁有的生命周期結(jié)合起來(lái)同時(shí)把調(diào)用保持在 FastMCPClient的完整表面上認(rèn)證、tracing、緩存、結(jié)果解析、進(jìn)度、多輪工具。使用場(chǎng)景分工直接操作原始 session 時(shí)選 SDK 的 group服務(wù)器已經(jīng)以 FastMCP 客戶端形態(tài)存在時(shí)選ClientGroup。源碼與測(cè)試導(dǎo)航設(shè)計(jì)筆記dev-docs/v4-notes/client-groups.md本文主體狀態(tài)為 In review #4904用戶文檔docs/clients/client-groups.mdx核心實(shí)現(xiàn)fastmcp_slim/fastmcp/client/group.pyToolRoute在 L22-L28ClientGroup在 L31from_config在 L62-L85list_tools在 L152-L187resolve_tool在 L189-L222call_tool/call_tool_mcp在 L224-L264測(cè)試套件tests/client/group/test_client_group.py覆蓋獨(dú)立協(xié)商、碰撞拒絕、懶加載共享發(fā)現(xiàn)、引用計(jì)數(shù)、并發(fā)進(jìn)入守衛(wèi)、部分失敗回滾、死服務(wù)器故障隔離、緩存刷新等 16 個(gè)場(chǎng)景客戶端引用計(jì)數(shù)與mode參數(shù)fastmcp_slim/fastmcp/client/client.py總結(jié)ClientGroup用最小的對(duì)外表面積解決了多服務(wù)器客戶端編排的三個(gè)實(shí)際問(wèn)題為不同協(xié)議時(shí)代的服務(wù)器各自保住獨(dú)立協(xié)商、用{server}_{tool}命名空間消除工具名沖突、把每次調(diào)用精確路由回發(fā)布它的客戶端及其完整能力面。它在單一聚合連接與裸客戶端集合之間提供了一個(gè)既有明確歸屬、又不過(guò)度設(shè)計(jì)的中間形態(tài)——無(wú)合成會(huì)話、成員不可變、按需刷新目錄、已知路由故障隔離這些不變式讓它在 Agent 集成這類(lèi)多服務(wù)器場(chǎng)景下既可預(yù)測(cè)又可組合。【免費(fèi)下載鏈接】fastmcp The fast, Pythonic way to build MCP servers and clients.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastmcp創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考