第 3 篇《MCP Python SDK v2 实战》把三原语的注册写法走了一遍:@mcp.tool() 把普通函数变成工具,函数名、docstring、类型提示合起来就是全部接口定义。但那些 handler 本质上仍是纯函数——参数进、结果出,执行期间外界一无所知。真实的工具远不止于此:批量任务要向客户端报进度,处理中途要读 server 自己暴露的资源,昂贵资源要全服务共享,有时还得在开工前向用户要一个确认。这些运行时能力,v2 收敛在两个机制里:注入给 handler 的 Context 对象,与声明式依赖 Resolve(fn)。
本篇是全系列第 4 篇、Server 开发层第 2 篇,按"Context 解构 → lifespan 共享资源 → Resolve 依赖注入 → MRTR 多轮往返 → 错误处理 → 实战"组织,读完你能把一个纯函数工具升级成带进度、带状态、能跟用户对话的完整 handler。结论均以 mcp 2.3.0 源码与官方文档站为准(本文写作时 2026 年 11 月)。
1、handler 不只是函数
纯函数模式有三个盲区。其一,长任务对客户端完全黑盒:模型发起 tools/call 后只能干等,中间没有任何反馈通道。其二,handler 够不着 server 自身的环境——连接池、启动配置、请求元数据,这些在函数参数里都没有入口。其三,工具参数由模型填,"这个值必须问用户本人"的诉求在纯函数模型里无解。
v2 的答案分两层。Context 负责注入运行时句柄:函数加一个注解为 Context 的参数,SDK 就把当前请求的上下文对象递进来,参数名任意、不需要可整个省略。Resolve 负责声明依赖:参数标成 Annotated[T, Resolve(fn)],这个参数不进工具 schema、不由模型填,改由 fn 在工具体运行前生成注入。handler 的常见诉求与提供方对照如下。
| 诉求 | 提供方 |
|---|---|
| 上报任务进度 | Context 的 report_progress |
| 读取本 server 资源 | Context 的 read_resource |
| 全服务共享昂贵资源 | lifespan 与 lifespan_context |
| 向用户收集输入 | Resolve 加 Elicit |
| 预期内的失败中止 | 抛 ToolError |
下文逐个展开,最后用一个批量导入工具把五件事串起来。
2、解构 Context 对象
先看注入写法与最常用的进度上报,示例如下。
from mcp.server.mcpserver import Context, MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
async def lengthy(task: str, ctx: Context) -> str:
"""执行一个长任务,期间向客户端上报进度。"""
for step in range(1, 11):
await ctx.report_progress(step, 10, message=f"步骤 {step} 完成")
return f"{task} 完成"
解读:参数注解为 Context 即触发注入,参数名随意;工具不需要它就整个删掉。report_progress(progress, total=None, message=None) 把进度通知推给客户端——GA 版里进度通知是纯 server-to-client 方向,客户端界面与模型都能看到长任务在推进。同一把句柄还能读资源:await ctx.read_resource("docs://catalog") 在工具里复用第 3 篇注册的资源,免得自己再写一遍读取逻辑。
2.1、日志族已废弃
v1 教程里常见的 await ctx.info("处理中") 在 v2 里别再写了:log 与 debug、info、warning、error 整族方法都标注了废弃(2026-07-28 起,SEP-2577),调用会触发 MCPDeprecationWarning,而这个警告默认就会打印(官方文档站 的 What's New 有说明)。MCP 级日志通道正在退出协议,服务端自有日志请回到 Python logging 模块——也顺带守住第 3 篇的告诫:stdio 模式下 stdout 是协议线,别用 print。
2.2、常用成员一览
Context 其余常用成员如下,均按 2.3.0 源码口径。
| 成员 | 类别 | 说明 |
|---|---|---|
| request_id | 属性 | 本次请求的唯一 ID |
| protocol_version | 属性 | 协商出的协议版本,请求外为 None |
| headers | 属性 | HTTP 传输携带的请求头,stdio 下为 None |
| client_capabilities | 属性 | 客户端声明的能力 |
| input_responses | 属性 | MRTR 重试轮带回传的答案,首轮为 None |
| request_state | 属性 | MRTR 重试轮回显的状态,首轮为 None |
| session | 属性 | 底层会话,进阶用法入口 |
两点提醒:headers 是客户端送来的输入,源码 docstring 明言不要把任何头当身份断言,鉴权走正式认证层;input_responses 与 request_state 服务第 5 节的多轮往返,先记位置。
3、lifespan 全会话共享
第 3 篇实战里,知识库的文档与向量都是模块级全局变量——demo 够用,工程上有短板:import 即建资源、难以按需清理、多进程各建一套。v2 的正解是 MCPServer 构造器的 lifespan 参数,且语义与 v1 有一个关键差异:streamable HTTP 下 lifespan 现在在启动时只跑一次,产出的状态被所有会话与请求共享;此前是每个会话各跑一次,无状态模式甚至每个请求跑一次(What's New 有明确说明)。连接池、缓存这类昂贵资源因此便宜了一个量级;反过来,每连接一份的资源现在应放进 handler 体内。写法如下。
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import httpx
from mcp.server.mcpserver import Context, MCPServer
@asynccontextmanager
async def app_lifespan(server: MCPServer) -> AsyncIterator[dict]:
async with httpx.AsyncClient(timeout=10) as http:
yield {"http": http}
mcp = MCPServer("Fetcher", lifespan=app_lifespan)
@mcp.tool()
async def fetch(url: str, ctx: Context) -> str:
"""抓取 URL 并返回正文开头。"""
http: httpx.AsyncClient = ctx.request_context.lifespan_context["http"]
resp = await http.get(url)
return resp.text[:500]
解读:lifespan 是一个收 server 实例、返回 async context manager 的函数,@asynccontextmanager 修饰最顺手;yield 出去的值就是共享状态,server 启动时进入、关停时清理。handler 一侧没有专门的取用方法,lifespan 上下文挂在请求上下文上,经 ctx.request_context.lifespan_context 访问;把工具参数注解写成 Context[dict],类型检查器还能认出它的类型。
注意:lifespan 只放全服务共享、无会话归属的资源。会话级状态塞进来会被并发请求互相踩踏,这类状态属于 handler 体内。
4、Resolve 依赖注入
最难的需求单独讲:工具执行前需要一个只有用户知道的值。第 2 篇在协议层给过答案——GA 版用 MRTR 把"还差输入"作为正常响应返回,老协议用 elicitation 反向请求客户端,两代报文完全不同。Resolve 就是 SDK 藏掉这层差异的方式:参数标 Annotated[T, Resolve(fn)],值改由 fn 生成注入,模型看不见这个参数。
fn 的规矩按源码口径:参数可以是 Context、嵌套的 Resolve(...)(构成依赖 DAG,注册期查环)、或按名字吃工具实参;返回值可以是普通值,也可以是三种请求标记——Elicit(message, schema) 问用户、Sample(...) 借客户端模型补全、ListRoots() 要文件系统根。示例如下。
from typing import Annotated
from pydantic import BaseModel
from mcp.server.mcpserver import (
AcceptedElicitation, Context, Elicit, ElicitationResult, MCPServer, Resolve,
)
class Overwrite(BaseModel):
agree: bool
async def ask_overwrite(filename: str) -> Elicit[Overwrite]:
return Elicit(f"{filename} 已存在,覆盖吗?", Overwrite)
@mcp.tool()
async def save_as(
filename: str,
overwrite: Annotated[ElicitationResult[Overwrite], Resolve(ask_overwrite)],
) -> str:
"""保存文件,重名时先征得用户同意。"""
if isinstance(overwrite, AcceptedElicitation) and overwrite.data.agree:
return f"已覆盖 {filename}"
return "用户未同意,未保存"
解读三个要点。其一,ask_overwrite 按名字收了工具实参 filename,问题文案因此能依赖运行时值,resolver 不只能问死问题。其二,消费形态有两种:注解为 T 直接拿解包值,用户拒绝或取消时 SDK 自动抛 ToolError 中止调用;注解为 ElicitationResult[T] 拿完整三态(AcceptedElicitation、DeclinedElicitation、CancelledElicitation)自己分支,例中选的是后者。其三,Elicit 绑定的 schema 只允许原始类型字段,渲染期强校验。同一段声明在两代协议上怎么落地,时序如下。
解读:GA 版链路里 resolver 不阻塞等待——SDK 把问题打包进 InputRequiredResult 的 input_requests,随 request_state 一并返回;客户端重试带回答案后,SDK 先核对答案对应的问题指纹:答案只对当初问出的原话生效,改写过措辞的问题会重新再问。旧协议链路则是同步反向请求,一问一答在连接内完成。每个问题只问一次,答案随 request_state 跨轮携带。
5、handler 侧的 MRTR
第 2 篇看的是 wire 报文(SEP-2322),handler 侧的接口就两个属性:ctx.input_responses 是客户端对上一轮 input_requests 的答案映射,ctx.request_state 是上一轮回显的不透明状态,首轮都为 None。Resolve 是推荐姿势,但 SDK 保留了手工通道——handler 直接返回 InputRequiredResult,示例如下。
from pydantic import BaseModel
from mcp_types import ElicitRequest, ElicitRequestFormParams, InputRequiredResult
from mcp.server.elicitation import render_elicitation_schema
class Confirm(BaseModel):
ok: bool
@mcp.tool()
async def deploy(env: str, ctx: Context) -> str | InputRequiredResult:
"""部署到指定环境,首轮征询确认。"""
if ctx.input_responses is None:
return InputRequiredResult(
input_requests={"confirm": ElicitRequest(
params=ElicitRequestFormParams(
message=f"确认部署到 {env}?",
requested_schema=render_elicitation_schema(Confirm),
))},
request_state=env,
)
answer = ctx.input_responses.get("confirm")
if answer is None or answer.action != "accept":
return "用户未确认,已取消"
return f"已部署到 {env}"
解读:手工模式要自己组装 input_requests——ElicitRequest 包 message 与 requested_schema(用 render_elicitation_schema 渲染,仍限原始类型),键名自定,第二轮按同样的键从 input_responses 取回答案;request_state 是原样回显的字符串,例中拿来携带 env。两条硬约束:返回注解必须带 InputRequiredResult 分支;一个调用只有一条 request_state 通道,同时声明 Resolve 参数又手工返回 InputRequiredResult,注册期就以 InvalidSignature 拒绝——两条流会互相覆盖状态、永远无法收敛。另有 v1 遗产 ctx.elicit(message, schema) 仍在:只对旧协议连接可用,2026-07-28 连接上没有反向通道,会以 NoBackChannelError 失败,新代码一律 Resolve。
6、用 ToolError 报错
第 3 篇 calc 的原则是业务错误当正常结果返回。但有一类失败不该伪装成结果:注定中止、且模型读了能自救的失败,抛 ToolError(源码见 python-sdk 仓库)。源码口径:从工具或 resolver 抛出,调用以 is_error=True 收场,你的消息进 content 给模型读,服务端 INFO 级记录、不带堆栈;其他任何异常(协议错误 MCPError 除外)都按崩溃处理——模型只看到 Error executing tool 工具名,原始信息不外泄,服务端 ERROR 级记完整堆栈。三条路径的归宿对比如下。
| 失败方式 | 模型看到 | 服务端日志 |
|---|---|---|
| 返回错误文案字符串 | 正常结果原文 | 无 |
| 抛 ToolError | is_error 结果附你的消息 | INFO 无堆栈 |
| 抛其他异常 | Error executing tool 工具名 | ERROR 带堆栈 |
改造第 3 节的 fetch,让网络失败走 ToolError,示例如下。
from mcp.server.mcpserver.exceptions import ToolError
@mcp.tool()
async def fetch(url: str, ctx: Context) -> str:
"""抓取 URL,网络失败时中止。"""
http: httpx.AsyncClient = ctx.request_context.lifespan_context["http"]
try:
resp = await http.get(url)
except httpx.HTTPError as exc:
raise ToolError(f"请求失败:{exc}") from exc
if resp.status_code >= 400:
raise ToolError(f"上游返回 {resp.status_code}")
return resp.text[:500]
解读:ToolError 的消息是给模型的修复线索,要带上足以让它改参数重试的信息。三个同族细节:SDK 对未知工具名、schema 校验失败自己也抛 ToolError;UnexpectedToolError 是 SDK 包装崩溃的子类,在 MCPServer.call_tool() 外围捕获它可区分预期失败与崩溃;pydantic 校验器里按惯例抛 ValueError,会落进参数校验失败这条预期通道。资源侧的对应物是 ResourceError 与 ResourceNotFoundError。
7、实战:带进度的批处理
把五个机制合体:批量拉取文档入库。lifespan 建共享 HTTP 客户端与存储,Resolve 在开工前问重复策略,工具循环里逐篇报进度。先看启动侧。
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
import httpx
from mcp.server.mcpserver import MCPServer
@asynccontextmanager
async def bulk_lifespan(server: MCPServer) -> AsyncIterator[dict]:
async with httpx.AsyncClient(timeout=30) as http:
yield {"http": http, "store": {}}
mcp = MCPServer("Bulk", lifespan=bulk_lifespan)
解读:连接池与文档仓都挂在 lifespan 上,所有会话共享一份,server 关停时随上下文一并清理。再看工具侧。
from typing import Annotated
from pydantic import BaseModel
from mcp.server.mcpserver import Context, Elicit, Resolve
class DupPolicy(BaseModel):
skip: bool # True 跳过重复,False 覆盖
async def ask_policy() -> Elicit[DupPolicy]:
return Elicit("遇到重复文档:跳过还是覆盖?", DupPolicy)
@mcp.tool()
async def import_docs(
urls: list[str],
policy: Annotated[DupPolicy, Resolve(ask_policy)],
ctx: Context,
) -> str:
"""批量拉取文档入库,实时上报进度。"""
pool = ctx.request_context.lifespan_context
done = 0
for url in urls:
name = url.rsplit("/", 1)[-1] or url
if name in pool["store"] and policy.skip:
continue
resp = await pool["http"].get(url)
pool["store"][name] = resp.text[:2000]
done += 1
await ctx.report_progress(done, len(urls), message=name)
return f"导入 {done} 篇,库存 {len(pool['store'])} 篇"
解读:policy 参数用的是解包注解,模型看不到它、也填不了它,值由 ask_policy 向用户要来;用户拒绝时 SDK 自动以 ToolError 中止,想自定义拒绝行为就换成 ElicitationResult[DupPolicy] 自己分支。进度每篇一报,客户端实时可见;store 跨调用累计、重启即清空,正好体现共享但非持久的定位。
8、总结
handler 从纯函数长成完整的运行时参与者:Context 按类型注入,report_progress 可用、log 整族已废弃;lifespan 启动一次、全会话共享,handler 经 request_context.lifespan_context 取用;Resolve 声明依赖,Elicit 标记问用户,两代协议自动分流,问题指纹保证答案不串轮;手工 InputRequiredResult 与 Resolve 互斥;ToolError 给模型可读的失败,其余异常对客户端不可见。留三道练习:
- 给第 3 篇知识库的 search 工具加进度上报,按批计算相似度时逐批 report_progress
- 把实战的 DupPolicy 改成 ElicitationResult 注解,用户拒绝时返回友好文案而非中止
- 写一个嵌套 resolver:ask_policy 依赖另一个 resolver 取默认策略,验证 DAG 与注册期查环
对于正在把工具做厚的读者,建议顺序是:先用 Context 补进度与资源读取,共享资源交给 lifespan,等真正要向用户开口再引入 Resolve。工具写厚之后的调试与接入真实宿主,本系列第 5 篇展开。

