MCP Python SDK · 第 10 章客户端进阶:传输、会话组与缓存

文档摘要

MCP Python SDK · 第 10 章客户端进阶:传输、会话组与缓存章节摘要:第 9 章你学会了用连一个服务、调几个方法。但真实场景往往更复杂——你要同时连三五个 MCP 服务,把它们的能力聚合成一个调用面;你要复用昂贵的响应、订阅资源变更、在断线后重连。本章就是把这些「生产级客户端」的需求讲透。核心有四块:一是客户端三种传输的接入细节(stdio 客户端、流式 HTTP 客户端、SSE 客户端各自的参数与陷阱);二是 (会话组)——一个聚合多个服务端的抽象,让你像调一个服务那样调一群服务;三是响应缓存( / ),让重复调用不重复计算;四是订阅(Subscriptions)与资源更新通知,让客户端在资源变化时即时感知。

MCP Python SDK · 第 10 章客户端进阶:传输、会话组与缓存

章节摘要:第 9 章你学会了用 Client 连一个服务、调几个方法。但真实场景往往更复杂——你要同时连三五个 MCP 服务,把它们的能力聚合成一个调用面;你要复用昂贵的响应、订阅资源变更、在断线后重连。本章就是把这些「生产级客户端」的需求讲透。核心有四块:一是客户端三种传输的接入细节(stdio 客户端、流式 HTTP 客户端、SSE 客户端各自的参数与陷阱);二是 ClientSessionGroup(会话组)——一个聚合多个服务端的抽象,让你像调一个服务那样调一群服务;三是响应缓存(CacheHint / CacheMode),让重复调用不重复计算;四是订阅(Subscriptions)与资源更新通知,让客户端在资源变化时即时感知。读完本章,你能用客户端做编排、做性能优化、做实时响应,真正把「消费 MCP 服务」做成一个生产系统。

学习目标

阅读完本章,你应当能够:

用三种客户端传输(stdio / 流式 HTTP / SSE)连接远程或本地服务,并说清各自的关键参数(如 stdio 的命令与环境变量、HTTP 的超时与重连)。
用 ClientSessionGroup(会话组) 把多个服务端聚合成一个调用面,通过命名区分各服务,统一调用工具与读取资源。
用 CacheHint / CacheMode 标注与服务端配合实现响应缓存,避免重复调用昂贵工具,并理解缓存的命中与失效规则。
用 订阅(Subscriptions) 监听资源变更通知,在资源内容变化时即时更新,而非轮询。
处理断线重连与传输错误,理解不同传输在重连语义上的差异。

核心概念速览

整章逻辑可浓缩为一句话:生产级客户端的复杂度不在「连一个服务」,而在「连一群服务、复用响应、感知变化、扛住断线」——ClientSessionGroup、缓存、订阅、重连这四件事,把客户端从「调用方」升级为「编排系统」。

子章节导航

01 三种客户端传输的接入细节

深入 stdio 客户端(StdioServerParameters 指定命令、参数、环境变量)、流式 HTTP 客户端(超时、重连、请求头)、SSE 客户端(现状与限制)。讲清各自的典型陷阱——stdio 的环境变量白名单、HTTP 的 DNS 与超时、SSE 的连接保持。用对照表收尾。

02 ClientSessionGroup:聚合多个服务端

会话组是客户端最有用的进阶抽象。讲清它如何让你注册多个服务端、用名字区分,然后统一调用——调用工具时可指定来源服务,读取资源时按 URI 路由。用一个「同时用数据库服务 + 文件服务 + 外部 API 服务」的编排场景说明它的价值。

03 响应缓存:CacheHint 与 CacheMode

讲清缓存的两端:服务端在响应上标注 CacheHint(可缓存性、键),客户端用 CacheMode 决定是否走缓存。用一个「昂贵计算工具」的例子说明如何避免重复调用,以及缓存键的构造与失效规则。对比「客户端缓存」与「服务端缓存」的边界。

04 订阅与资源更新通知

资源不是静态的——文件会变、数据库行会更新。订阅(Subscriptions)让客户端在资源变化时收到通知,而非轮询。讲清 subscribe 的工作机制、服务端的 SubscriptionBus 如何广播、以及订阅与资源列表变更通知(list_changed)的关系。

05 断线重连与传输错误处理

生产环境网络不稳。讲清不同传输在重连语义上的差异:stdio 子进程崩溃如何重启、流式 HTTP 的可重连性、SSE 的连接保持与断开。给出一个通用的重连模式(指数退避 + 状态恢复),并说明哪些会话状态可恢复、哪些不能。

子章节之间的逻辑关系

本章遵循「接入 → 编排 → 优化 → 感知 → 容错」的递进,五块共同构成生产级客户端的能力图谱:


传输接入 (01) ── 三种传输的细节与陷阱
   │
   ▼
会话组 (02)  ── 聚合多服务,统一调用面
   │
   ▼
响应缓存 (03) ── 避免重复计算
   │
   ▼
订阅 (04)    ── 资源变化的即时感知
   │
   ▼
重连 (05)    ── 传输错误恢复
   │
   ▼
第 11 章:给这套客户端连接加上认证保护

传输接入是基础,会话组让你编排多服务,缓存让你省钱省时,订阅让你实时,重连让你可靠。这五块解决的是「消费 MCP 服务」在生产环境里的全部核心痛点。本章与第 9 章共同撑起「客户端与服务端并重」的承诺——客户端不是一章带过,而是被认真讲透。

前置知识与后续延伸

前置知识:

第 9 章的 Client 构造与生命周期(本章是其进阶)
第 8 章的传输层(理解客户端接入的底层传输)
第 4 章的结构化输出(理解缓存的对象是什么)
第 5 章的资源概念(订阅的对象是资源)

本章为后续章节奠定的基础:

会话组编排是多服务架构的基础,第 11 章(认证)会扩展到「带认证的多服务」
缓存机制会在第 12 章(中间件)被引用为可拦截点
订阅模式是理解「服务端推送」的入口,与第 7 章(单向通知)呼应
重连模式会被附录速查与排错收录

MCP Python SDK · 第 10 章 客户端进阶:传输、会话组与缓存

文档摘要