MCP Python SDK · 第 9 章客户端入门:Client 与会话

文档摘要

MCP Python SDK · 第 9 章客户端入门:Client 与会话章节摘要:客户端主线开始。前面八章你都在「写服务端」,现在换视角——写消费 MCP 服务的客户端。v2 把升级成了第一类对象,这一章就是讲透它。核心洞见是: 把「选传输、开连接、协商协议版本、维持会话」这一整套细节,收敛成了一个对象——你只管 ,然后 / ,传输是什么、协议版本怎么协商,它替你处理。我们会讲清它的构造(按参数类型自动选传输:服务对象→内存、URL→流式 HTTP、传输对象→直用)、生命周期、核心调用方法、协议版本协商( 参数),以及它与低层的关系。读完本章,你能用十几行代码连上任意 MCP 服务并消费它的全部能力。

MCP Python SDK · 第 9 章客户端入门:Client 与会话

章节摘要:客户端主线开始。前面八章你都在「写服务端」,现在换视角——写消费 MCP 服务的客户端。v2 把 Client 升级成了第一类对象,这一章就是讲透它。核心洞见是:Client 把「选传输、开连接、协商协议版本、维持会话」这一整套细节,收敛成了一个对象——你只管 async with Client(...) as client:,然后 client.call_tool(...) / client.read_resource(...),传输是什么、协议版本怎么协商,它替你处理。我们会讲清它的构造(按参数类型自动选传输:服务对象→内存、URL→流式 HTTP、传输对象→直用)、async with 生命周期、核心调用方法、协议版本协商(mode 参数),以及它与低层 ClientSession 的关系。读完本章,你能用十几行代码连上任意 MCP 服务并消费它的全部能力。

学习目标

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

用三种方式构造 Client:传入服务端对象(内存)、传入 URL 字符串(流式 HTTP)、传入传输对象(直用),并说清它如何按参数类型自动选传输。
用 async with Client(...) as client: 管理连接生命周期,理解构造期只选传输、进入上下文才真正打开连接的设计。
调用核心方法:call_tool(调工具并拿结构化输出)、list_tools / list_resources / list_prompts、read_resource、get_prompt。
解释协议版本协商——mode="auto"(协商)、mode="legacy"(强制 initialize 握手)的差异,以及为何现代连接(2026-07-28)无需握手。
区分第一类 Client 与低层 ClientSession,知道何时该用哪个(绝大多数场景用 Client,需要细粒度控制才下沉到 ClientSession)。

核心概念速览

整章逻辑可浓缩为一句话:v2 的 Client 是一个「连接即对象」的抽象——你给它一个服务端对象、一个 URL 或一个传输,它替你把选传输、开连接、协商版本、维持会话全做完,你只剩下「调用方法」这一件事要关心。

子章节导航

01 Client 的构造:按参数类型自动选传输

讲清 Client 单参数构造的三种形态:传服务端对象→内存传输(进程内直连,测试/嵌入用);传 URL 字符串→流式 HTTP 传输(连远程服务);传传输对象→直用。这个「按类型分发」的设计让客户端代码在不同部署间切换几乎零成本。

02 连接生命周期:async with 与协议协商

讲清构造期与连接期的分离——Client(...) 只选传输,async with ... as client: 才真正打开连接、协商协议版本、交换能力声明。然后展开 mode 参数:auto(协商,默认)、legacy(强制旧版 initialize 握手)、特定版本字符串。说明现代连接(2026-07-28)为何无需握手。

03 核心调用方法:调用工具、读取资源、获取提示词

逐个讲清日常用的方法:call_tool(调工具,返回 content 与 structured_content)、list_tools / list_resources / list_resource_templates / list_prompts、read_resource(读资源内容)、get_prompt(渲染提示词消息)。用对照表说明每个方法对应服务端的哪个原语。

04 客户端能力声明:告诉服务端「我支持什么」

服务端声明能力,客户端也声明能力——它告诉服务端自己支持采样、根、引导填写等反向能力。讲清这套双向声明如何工作,以及客户端能力声明如何影响服务端的行为(如服务端发现客户端不支持引导填写,就不会尝试)。

05 第一类 Client 与低层 ClientSession 的关系

收尾性的一节。讲清 Client 是 ClientSession 之上的便捷封装:它替你管理传输与连接,内部维持一个 ClientSession。绝大多数场景用 Client 就够;只有当你需要细粒度控制(自定义握手、直接操作协议对象、复用传输跑多个会话)时,才下沉到 ClientSession。

子章节之间的逻辑关系

本章遵循「会构造 → 懂生命周期 → 会调用 → 懂双向声明 → 知道何时下沉」的递进,让你从「能连上」到「连得对、连得精」:


构造 (01)    ── 三种参数,自动选传输
   │
   ▼
生命周期 (02) ── async with + 协议协商
   │
   ▼
调用方法 (03) ── 调工具、读资源、拿提示词
   │
   ▼
能力声明 (04) ── 客户端也声明,双向匹配
   │
   ▼
ClientSession (05) ── 何时下沉到低层
   │
   ▼
第 10 章:客户端进阶——传输、会话组、缓存、订阅

会构造是起点,懂生命周期让你不踩「连接没打开就调用」的坑,会调用让你真正消费服务端能力,懂双向声明让你理解为什么有些功能「服务端写了却用不了」,知道何时下沉让你在遇到 Client 的能力边界时有逃生口。本章是客户端主线的根基,第 10 章的所有进阶内容都建立在这里。

前置知识与后续延伸

前置知识:

第 1 章的内存客户端体验(知道 Client(mcp) 长什么样)
第 2 章的能力声明概念(理解客户端为何要「问声明过的方法」)
第 8 章的传输层(理解 Client 自动选的是哪些传输)

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

call_tool 的返回结构(structured_content)是第 4 章(结构化输出)的客户端视角
协议版本协商是第 7 章(MRTR 在现代连接上的工作方式)的对应面
Client 与 ClientSession 的关系是第 10 章(会话组)的直接前提
客户端能力声明会在第 7 章(采样、根)、第 11 章(认证)再次出现

MCP Python SDK · 第 9 章 客户端入门:Client 与会话

文档摘要