mcp-use V2 中的 Sampling 边界：为什么弃用服务端发起采样，以及正确的无会话替代模式

后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载导读mcp-use V2 有意不再支持传统的服务端发起server-initiatedSampling 回调——旧机制依赖一条长连接/持久会话而 V2 采用了无状态、按请求重建的无会话架构。本文以仓库中的 sampling 示例 为骨架讲清这一设计取舍背后的原理并给出标准的替代模式服务端返回确定性结果让宿主host/模型自行完成推理再通过一次普通工具调用把结果传回。读完你将掌握在无会话架构下正确设计需要模型参与的工具的方法以及如何用pnpm dev快速验证这一边界。背景MCP 协议中两股不同方向的 Sampling在 MCP 协议语境下Sampling 指让某一边的 LLM 参与生成内容它存在两个方向方向谁发起依赖条件客户端采样client sampling工具执行期间由服务端调用ctx.sample()客户端在capabilities中声明sampling能力服务端采样server-initiated sampling callback旧式服务端主动向客户端发起请求一条长期存活的连接/会话legacy sessionmcp-use 官方 Sampling 指南 系统讲解了客户端采样方向ctx.sample()允许工具在执行期间借用已连接客户端的模型、凭据与策略完成一次补全适合总结、分类、生成草稿等需要模型判断但服务端又不想自持 LLM 提供方集成的场景。而本文的 sampling 示例 讨论的则是另一个方向的边界问题——服务端发起采样回调在 V2 中为何被明确拒绝以及开发者应该用什么模式来代替。核心结论V2 有意不支持服务端发起采样示例 README 的第一句话即点明立场The legacy server-initiated sampling callback is intentionally unsupported in mcp-use V2: it relied on a long-lived connection/session.关键信息有三个有意intentionally不支持不是遗漏而是设计决策弃用理由是它依赖长连接/会话long-lived connection/session示例提供了一种确定性deterministic工具结果来替代让宿主自己处理模型工作再把结果通过一次普通工具调用传回。这一决策在源码中可以得到印证。在 server.ts 的ClientUsage结构中连接模式被明确区分为两类connection_mode: stateless_request | legacy_session; sampling_capability: boolean; elicitation_capability: boolean;其中sampling_capability通过Object.hasOwn(capabilities, sampling)检测客户端是否声明了采样能力server.ts而connection_mode在现代modern协议时代被固定为stateless_request仅在传统legacy时代才是legacy_sessionserver.ts。也就是说V2 的现代协议路径本质上是无状态的按请求连接没有可供服务端回调使用的长期会话通道。旧的 server-to-client sampling 回调恰恰需要这样的通道因此两者无法共存——这是架构层面有意不支持的根本原因。注意区分客户端方向的ctx.sample()依赖客户端声明sampling能力在 V2 中依然受支持本文与示例反对的只是服务端主动发起、依赖长会话的旧回调方向。示例逐行拆解一个声明 Sampling 边界的确定性工具示例源码位于 libraries/typescript/packages/server/examples/sampling/src/index.ts完整代码仅约 40 行我们先看服务端初始化import { MCPServer } from mcp-use; import { z } from zod; const server new MCPServer({ name: sampling-example, version: 1.0.0, title: Sampling boundary, description: Documents the V2 sampling boundary without relying on sessions., });MCPServer来自mcp-useTypeScript 服务端包zod用于声明输入/输出 schema元信息name、version、title、description直接点明该示例的使命在不依赖会话的前提下把 V2 的 Sampling 边界讲清楚。接着注册唯一的工具explain-samplingserver.tool( { name: explain-sampling, description: Explain whether server-initiated sampling is available., inputSchema: z.object({ task: z.string().min(1) }), outputSchema: z.object({ task: z.string(), supported: z.literal(false), guidance: z.string(), }), annotations: { readOnlyHint: true }, }, async ({ task }) { // mcp-use deliberately does not expose the old server-to-client sampling // callback. It depended on a long-lived session, which V2 no longer has. const data { task, supported: false as const, guidance: Ask the host/model to perform this task, then call a tool with its result., }; return { content: [{ type: text, text: data.guidance }], structuredContent: data, }; } ); export default server;这个工具的设计本身就是对Sampling 边界的声明值得注意的几个技术点1. 输入/输出 schema 用类型系统锁死边界。输入task至少 1 个字符输出用z.literal(false)把supported字段永远固定为false——从类型层面保证服务端发起采样不可用这一事实不可能被误报。2.annotations: { readOnlyHint: true }。标记该工具是只读的客户端可以据此安全地调用、缓存或并发执行不必担心副作用符合采样边界说明这类纯查询型工具的定位。3. 双通道返回contentstructuredContent。返回体同时给出人类可读的文本content与结构化数据structuredContent前者供展示后者供程序化消费——这正是把决定权交给宿主的载体。4. 注释即契约。代码注释直接复述了 README 的核心论断mcp-use 有意不暴露旧的 server-to-client sampling 回调因为它依赖 V2 已不再存在的长连接会话。替代模式让宿主做模型工作用普通工具调用传回结果示例给出的guidance文本就是 V2 推荐的替代流程的精炼表达Ask the host/model to perform this task, then call a tool with its result.把这句话展开为可执行的三步模式服务端保持确定性工具不调用任何模型只返回当前任务的元信息如task、supported: false与下一步指引宿主接管模型工作客户端侧的主机/Agent 读取工具结果后自行调用其绑定的 LLM 完成需要模型判断的部分总结、分类、生成草稿等结果经普通工具调用回流宿主把模型产出的结果作为参数再次调用某个工具或触发后续工具链传回服务端服务端继续执行确定性逻辑。这套模式的优势在于不依赖会话每一步都是标准的请求-响应天然契合 V2 的stateless_request连接模式权限边界清晰模型推理发生在持有模型、凭据与策略的宿主侧服务端不越权、不自持 LLM 集成可回退即便宿主不支持任何采样工具结果本身也是完整、确定性的链路不会中断。何时仍然应该使用ctx.sample()客户端采样需要强调的是弃用旧回调不等于放弃 Sampling 能力本身。如果客户端声明了sampling能力工具内仍可通过ctx.sample()借用客户端模型官方指南 docs/typescript/server/sampling.mdx 给出了成熟写法if (!ctx.client.can(sampling)) { return text( Received ${input.length} characters. Sampling is not available., ); } const response await ctx.sample( Classify this text as positive, negative, or neutral. Return one word.\n\n${input}, );判据很简单当客户端已具备正确的模型、凭据、策略或用户上下文时优先用客户端采样当需要跨工具链路、或在无法保证客户端支持采样的场景下采用本文的确定性工具 宿主处理模式。二者都以服务端不拥有 LLM 集成为前提区别只在于模型工作发生在工具调用之内还是之外。运行与验证示例的 package.json 提供了一套完整的开发闭环pnpm dev # 启动开发服务器mcp-use dev pnpm build # 构建mcp-use build pnpm start # 启动构建产物mcp-use start pnpm typecheck # 类型检查tsc --noEmit进入示例目录执行pnpm dev即可启动cd libraries/typescript/packages/server/examples/sampling pnpm dev启动后可以用支持 MCP 的客户端如 mcp-use Inspector连接并调用explain-sampling工具传入任意task观察返回supported恒为falseguidance提示宿主自行完成模型工作。该示例还接入了仓库的示例验证体系在 examples/registry.mjs 中它被注册为local(sampling, { tools: [explain-sampling], scenario: sampling }),而package.json里的verify脚本会调用node ../verify-examples.mjs --examplesampling即通过mcp-use/client启动示例并通过 HTTP 实际调用explain-sampling工具来断言其行为——这意味着示例的可运行性本身就是被仓库测试持续保障的你可以放心把它当作自己实现 Sampling 边界时的最小参照。小结mcp-use V2有意不支持传统的服务端发起采样回调因为它依赖长连接/会话与 V2 的stateless_request无会话架构冲突参见 server.ts 的ClientUsage结构正确替代模式是服务端返回确定性工具结果 → 宿主自行完成模型推理 → 通过普通工具调用把结果传回示例explain-sampling工具用z.literal(false)、readOnlyHint与structuredContent把这一边界在类型层面固化下来若客户端声明了sampling能力工具内仍可使用ctx.sample()借用客户端模型两者按模型工作发生在工具内还是工具外进行取舍通过 sampling 示例 的pnpm dev可快速体验其行为由仓库的 verify-examples.mjs 持续验证。赞分享后端MCP 服务MCP ClientsAI Agent人工智能【免费下载链接】mcp-useThe fullstack MCP framework to develop MCP Apps for ChatGPT / Claude MCP Servers for AI Agents.项目地址https://gitcode.com/gh_mirrors/mc/mcp-use点击查看免费下载相关推荐MCP Python SDK 采样Sampling实战服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移MCP Python SDK 采样Sampling实战服务端借道客户端 LLM 的逆向调用与 2026 协议弃用迁移 导读 本文围绕官方 Python S人工智能MCP 服务MCP Clientsrust-clippy 安装指南为什么 crates.io 安装已弃用以及如何用 rustup 正确安装 Clippyrust clippy 安装指南为什么 crates.io 安装已弃用以及如何用 rustup 正确安装 Clippy 本篇文章以 rust clippy静态分析代码质量开发工具rustc 错误码 E0328 深度解读为什么不能手动实现 Unsize以及用 CoerceUnsized 替代的正确姿势rustc 错误码 E0328 深度解读为什么不能手动实现 Unsize 以及用 CoerceUnsized 替代的正确姿势 导读 E0328 是 rust编程语言编译器语言运行时标准库上一篇猫抓浏览器资源嗅探扩展你的网页视频下载终极解决方案下一篇3步解锁加密音频ncmdump实现NCM转MP3的高效方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考