MCP Python SDK 采样(Sampling)实战:服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移

原创2026-09-19 16:10:512,244 阅读
文章标签:人工智能大模型MCP 服务MCP Clients工具调用后端

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(lowlevel Server)的同款服务端。

命令一: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)

原文档列出的限制值得逐条理解,它们是该特性的边界:

  1. 仅限 legacy 时代。sampling/createMessage 是服务端发起的请求,在 2026-07-28 协议中没有对应的线缆载体(wire carrier),因此故事必须用 era = "legacy" 运行,脚手架也会把握手路径钉死在 legacy 上。这也解释了为什么 HTTP 命令要带 --legacy。
  2. API 已弃用。ctx.session.create_message() 被 @deprecated 标注,示例中的 # pyright: ignore[reportDeprecated] 是刻意保留的;弃用替代方案是服务端直接调用自己的 LLM 提供商,不存在后继的 server→client 调用。
  3. 临时的两层路径。ctx.session.* 是 interim 2-hop path(工具 → 会话 → 客户端),README 预告后续版本会缩短这一链路——在弃用背景下,可理解为该链路最终会被整体移除而非优化。
  4. 子能力不可达。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 的统一测试矩阵:

manifest 中 [story.sampling] 的 era = "legacy"、status = "deprecated" 会驱动测试按 legacy 时代运行,并在输出中标记 (stdio/legacy) 或 (http/legacy) 的成功/失败状态。跑通整套矩阵即可验证:回调注册 → 能力通告 → 服务端发起请求 → 客户端应答 → 文本原样回传的完整闭环没有被任何一处打破。

登录后查看全文
python-sdk