MCP Python SDK 采样(Sampling)实战:服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移
MCP Python SDK 采样(Sampling)实战:服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移
导读
本文围绕官方 Python SDK 仓库中 sampling 故事示例 展开,讲解 MCP 中一种"方向反转"的调用形态:服务端不持有任何模型 API Key,在工具执行中途通过 sampling/createMessage 请求客户端用其宿主 LLM 完成一次补全。读完本文,你将掌握高层(MCPServer)与低层(lowlevel Server)两套 API 下注册 sampling 回调、发起请求的完整写法,理解回调注册即能力通告的机制,以及该特性在 2026-07-28 协议(SEP-2577)中被弃用后的正确迁移路径。
弃用声明(原文档原文语义):Sampling 已在 2026-07-28 协议(SEP-2577)中标记为 Deprecated,在弃用窗口期内仍可正常工作。官方迁移建议是:服务端直接调用你自己的 LLM 提供商,而不再经由客户端转发补全请求。
Sampling 是什么:被反转的 MCP 调用方向
常规 MCP 调用中,客户端请求服务端执行工具。而 Sampling(采样)正好相反:
- 服务端在工具函数体内发起
ctx.session.create_message(...),构造一个"服务器 → 客户端"的请求; - 客户端通过注册
sampling_callback回调来应答这个请求,回调内部通常调用宿主的 LLM 提供商,把补全结果原样返回给服务端; - 服务端不保存模型 API Key,模型能力完全来自客户端侧。
原文档用一句话点破这种反向关系:"A tool that asks the client's LLM for a completion mid-call — the inverted MCP direction."
注册回调本身还承担着能力通告职责:客户端在握手阶段通告 sampling 能力,唯一的触发条件就是构造时传入了 sampling_callback,没有单独的开关 flag。这一点与源码一致——在 src/mcp/client/client.py 中可以看到 sampling_callback 与 sampling_capabilities 两个字段,前者是回调解耦的挂载点,后者用于声明 sampling 的子能力(如 tools-in-sampling)。
运行示例:stdio 与 HTTP 两种形态
故事目录结构如下(examples/stories/sampling/):
client.py:客户端主程序,注册回调并发起工具调用;server.py:高层 API(MCPServer)服务端;server_lowlevel.py:低层 API(lowlevelServer)的同款服务端。
命令一:stdio(默认,客户端以子进程拉起服务端)
uv run python -m stories.sampling.client
命令二:HTTP(客户端自托管服务端)
--http 会让客户端在一个空闲端口上自行托管兄弟服务端,运行完毕再拆掉:
# 客户端自托管高层 API 服务端,显式使用 legacy 时代握手
uv run python -m stories.sampling.client --http --legacy
# 同一命令,但换成低层 API 的服务端变体
uv run python -m stories.sampling.client --http --legacy --server server_lowlevel
这里的 --legacy 不是可选项而是语义必需项:sampling 是 legacy 时代的特性,握手必须走旧路径。其背后的强制逻辑可以从故事矩阵配置看出——examples/stories/manifest.toml 中 [story.sampling] 明确写死 era = "legacy"、status = "deprecated",即使 HTTP 传输默认按 modern 时代解析,该故事也会被 manifest 覆盖回 legacy。
故事脚手架在做什么
两个命令都依赖 stories 脚手架模块(不属于 sampling 主题本身,但理解它能帮你跑通示例):
- examples/stories/_harness.py:
run_client()负责解析 argv——无 flag 走 stdio、--http <url>连接你自起的服务端、裸--http则用_self_hosted()在子进程里自托管兄弟服务端并等待 TCP 就绪;它还会根据时代计算mode(modern 传LATEST_MODERN_VERSION、legacy 传"legacy"),并最终以main(target, mode=...)显式传入。 - examples/stories/_hosting.py:
run_server_from_args()是服务端入口——裸参数走 stdio,--http --port N [--path /mcp]则起 uvicorn 监听 127.0.0.1。
客户端视角:注册 sampling_callback 即完成全部接入
client.py 的主体极短,因为它刻意只演示"接入点":
from mcp.client import Client, ClientRequestContext
from mcp.types import CreateMessageRequestParams, CreateMessageResult, TextContent
from stories._harness import Target, run_client
async def on_sample(context: ClientRequestContext, params: CreateMessageRequestParams) -> CreateMessageResult:
# 真实宿主在这里调用自己的 LLM 提供商;
# 示例返回确定性结果,使往返过程可被断言验证。
return CreateMessageResult(
role="assistant",
content=TextContent(text="[canned summary]"),
model="stub-model",
stop_reason="endTurn",
)
async def main(target: Target, *, mode: str = "auto") -> None:
async with Client(target, mode=mode, sampling_callback=on_sample) as client:
result = await client.call_tool("summarize", {"text": "hello world"})
assert not result.is_error, result
assert isinstance(result.content[0], TextContent)
assert result.content[0].text == "[canned summary]", result.content[0].text
if __name__ == "__main__":
run_client(main)
回调签名与底层类型约束
on_sample 接收 (ClientRequestContext, CreateMessageRequestParams) 并返回 CreateMessageResult,这并非约定俗成,而是被类型系统钉死的协议。在 src/mcp/client/session.py 中定义了 SamplingFnT Protocol:
class SamplingFnT(Protocol):
async def __call__(
self,
context: ClientRequestContext,
params: types.CreateMessageRequestParams,
) -> types.CreateMessageResult | types.CreateMessageResultWithTools | types.ErrorData: ...
值得注意的是,返回值可以是普通结果,也可以是 ErrorData——回调完全可以用结构化错误拒绝某次采样请求。若客户端未注册回调,SDK 提供默认回调 _default_sampling_callback(src/mcp/client/session.py),它直接返回 ErrorData(code=INVALID_REQUEST, message="Sampling not supported"),即"没注册就不通告能力、来了请求就礼貌拒绝"。
客户端收到服务端发来的 sampling/createMessage 请求后,由会话层分发到该回调(src/mcp/client/session.py 的 return await self._sampling_callback(ctx, p) 即分发点)。示例用固定文本 "[canned summary]" 充当应答,就是为了让端到端往返可断言:call_tool 返回的内容必须逐字节等于回调给出的文本,跑通即证明整条"服务端 → 客户端 → 回服务端"链路完整。
服务端视角:在工具体内调用 ctx.session.create_message
server.py 用高层 API 展示了服务端发起采样:
from mcp.server.mcpserver import Context, MCPServer
from mcp.types import SamplingMessage, TextContent
from stories._hosting import run_server_from_args
def build_server() -> MCPServer:
mcp = MCPServer("sampling-example")
@mcp.tool(description="Summarize text by asking the host's LLM via sampling/createMessage.")
async def summarize(text: str, ctx: Context) -> str:
result = await ctx.session.create_message( # pyright: ignore[reportDeprecated]
messages=[SamplingMessage(role="user", content=TextContent(text=f"Summarize in one sentence:\n\n{text}"))],
max_tokens=200,
)
assert isinstance(result.content, TextContent)
return result.content.text
return mcp
if __name__ == "__main__":
run_server_from_args(build_server)
没有 Context.sample() 糖衣:ctx.session 才是公共路径
原文档特意强调:SDK 没有提供 Context.sample() 之类的便捷方法,ctx.session 就是唯一的公共入口。这层"隔一跳"的设计(interim 2-hop path)在弃用迁移背景下是有意为之——官方预期该特性将被移除,因此不再为其包装更高层糖衣。
create_message 的完整参数
create_message 在 src/mcp/server/session.py 中定义,带三组 @overload(按是否传入 tools / tool_choice 区分返回类型),且全部标注了 @deprecated(...) 装饰器。核心参数如下:
| 参数 | 类型 | 说明 |
|---|---|---|
messages |
list[SamplingMessage] |
会话消息列表,必填,每条约含 role 与 content(文本或图片) |
max_tokens |
int |
最大生成 token 数,必填 |
system_prompt |
str | None |
可选的系统提示词 |
include_context |
IncludeContext | None |
上下文携带选项;仅当客户端具备 sampling.context 能力时才应设为 "thisServer" 或 "allServers" |
temperature |
float | None |
采样温度 |
stop_sequences |
list[str] | None |
停止序列 |
metadata |
dict[str, Any] | None |
透传给 LLM 提供商的元数据 |
model_preferences |
ModelPreferences | None |
模型选择偏好 |
tools |
list[Tool] | None |
采样期间允许 LLM 使用的工具,要求客户端具备 sampling.tools 能力 |
tool_choice |
ToolChoice | None |
工具使用行为控制,同样要求 sampling.tools 能力 |
related_request_id |
RequestId | None |
关联请求的 ID |
传入 tools 或 tool_choice 时返回 CreateMessageResultWithTools(内容可承载工具调用结果数组),否则返回普通 CreateMessageResult。
关于 pyright: ignore[reportDeprecated]
示例中 ctx.session.create_message(...) 旁刻意保留了一行 # pyright: ignore[reportDeprecated]。这是有意为之:方法本身已被弃用,类型检查器会告警,但示例必须演示这条仍在弃用窗口期内可用的路径,因此显式压制告警而非删掉调用。真实新项目应遵循迁移路径(见下文),而非照抄这行 ignore。
低层 API 变体:手搓工具列表与 CallToolResult
server_lowlevel.py 用低层 Server API 复刻同一功能,展示同一请求在 ServerRequestContext.session 上的等价写法,且 ListToolsResult 与 CallToolResult 全部手工构造:
from typing import Any
import mcp.types as types
from mcp.server.context import ServerRequestContext
from mcp.server.lowlevel import Server
from stories._hosting import run_server_from_args
def build_server() -> Server[Any]:
async def list_tools(
ctx: ServerRequestContext[Any], params: types.PaginatedRequestParams | None
) -> types.ListToolsResult:
return types.ListToolsResult(
tools=[
types.Tool(
name="summarize",
description="Summarize text by asking the host's LLM via sampling/createMessage.",
input_schema={
"type": "object",
"properties": {"text": {"type": "string"}},
"required": ["text"],
},
),
]
)
async def call_tool(ctx: ServerRequestContext[Any], params: types.CallToolRequestParams) -> types.CallToolResult:
assert params.name == "summarize"
assert params.arguments is not None
prompt = f"Summarize in one sentence:\n\n{params.arguments['text']}"
result = await ctx.session.create_message( # pyright: ignore[reportDeprecated]
messages=[types.SamplingMessage(role="user", content=types.TextContent(text=prompt))],
max_tokens=200,
)
assert isinstance(result.content, types.TextContent)
return types.CallToolResult(content=[types.TextContent(text=result.content.text)])
return Server("sampling-example", on_list_tools=list_tools, on_call_tool=call_tool)
高层与低层两个变体共用 stories._hosting.run_server_from_args 托管逻辑(stdio 或 uvicorn),只差在 API 风格:高层用装饰器与 Context 注入,低层用显式回调函数与 ServerRequestContext。这条"同一故事、两套 API"的双轨写法在 stories 目录中是通用模式——manifest 中 lowlevel = true(默认)即表示该故事会同时针对 server_lowlevel.build_server() 跑一遍主程序。
限制与注意(Caveats)
原文档列出的限制值得逐条理解,它们是该特性的边界:
- 仅限 legacy 时代。
sampling/createMessage是服务端发起的请求,在 2026-07-28 协议中没有对应的线缆载体(wire carrier),因此故事必须用era = "legacy"运行,脚手架也会把握手路径钉死在 legacy 上。这也解释了为什么 HTTP 命令要带--legacy。 - API 已弃用。
ctx.session.create_message()被@deprecated标注,示例中的# pyright: ignore[reportDeprecated]是刻意保留的;弃用替代方案是服务端直接调用自己的 LLM 提供商,不存在后继的 server→client 调用。 - 临时的两层路径。
ctx.session.*是 interim 2-hop path(工具 → 会话 → 客户端),README 预告后续版本会缩短这一链路——在弃用背景下,可理解为该链路最终会被整体移除而非优化。 - 子能力不可达。README 提示高层
Client没有sampling_capabilities=构造 kwarg,sampling.tools子能力(工具参与采样)无法从高层客户端触达;若确需该子能力,应降级到ClientSession。需要说明的是,从当前源码看,src/mcp/client/client.py 的配置字段中已存在sampling_capabilities(并在 src/mcp/client/client.py 透传给会话),但 README 提示的语义依然成立:tools-in-sampling 这条子能力路径在高层客户端上并未真正打通,需要ClientSession级别才可用。
协议依据与迁移建议
- 规范章节:该特性对应的协议章节名称为 "Sampling — client features"(2025-11-25 客户端特性部分)。仓库中 schema/2025-11-25.json 保留了该时代的协议定义,可与示例对照查看线缆消息形状。
- 迁移路径(SEP-2577):既然 2026-07-28 协议移除了
sampling/createMessage的载体,新的实现方式是在服务端进程内直接调用你自己的 LLM 提供商,把"让客户端代为生成"改写为"服务端自己生成",消除对宿主回调的依赖。这也意味着:需要模型能力又不想持有 Key 的场景,在 2026 时代应从架构层面重新设计(例如独立的模型网关),而不是继续依赖客户端采样。 - 同类兄弟故事:
legacy_elicitation/与roots/与 sampling 共享同一套 legacy 时代 server→client 请求形态,可对照阅读——examples/stories/legacy_elicitation/README.md 与 examples/stories/roots/README.md。
测试矩阵:如何验证这条往返链路
sampling 故事纳入了 stories 的统一测试矩阵:
- tests/examples/test_stories.py:按 manifest 展开的故事矩阵测试,逐条跑 client 主程序;
- tests/examples/test_stories_smoke.py:冒烟测试;
- tests/examples/test_story_shape.py:校验故事目录结构与 manifest 一致性(例如
[story.*]键与含client.py的故事目录一一对应)。
manifest 中 [story.sampling] 的 era = "legacy"、status = "deprecated" 会驱动测试按 legacy 时代运行,并在输出中标记 (stdio/legacy) 或 (http/legacy) 的成功/失败状态。跑通整套矩阵即可验证:回调注册 → 能力通告 → 服务端发起请求 → 客户端应答 → 文本原样回传的完整闭环没有被任何一处打破。