一、核心定义与本质1. 什么是 MCP Sampling采样Sampling 是 MCP 独有的反向 LLM 调用能力 MCP Server 在执行逻辑Tool/Resource/Prompt中途主动向 MCP ClientVSCode Copilot / Claude Desktop / Cursor发起sampling/createMessage请求借用客户端自带的大模型生成文本、图片、音频服务端无需持有任何 LLM API Key、不用对接 OpenAI/Gemini 接口Model Cont...。2. 核心设计价值解决传统开发痛点密钥统一托管在客户端用户在 VSCode/Claude 配置好 Gemini/Claude API所有接入的 MCP Server 共用这套模型权限服务端不用管理密钥、支付费用。人类在环安全机制Human-in-the-loop每次服务端发起采样请求客户端弹窗让用户预览 / 编辑提示词、允许 / 拒绝生成杜绝恶意服务端私自调用模型消耗额度、泄露上下文modelconte...。嵌套智能 Agent 能力Server 执行 Tool比如你的createUser创建用户中途可中途调用 LLM 做分类、摘要、翻译、推理实现工具内嵌套 AI 思考构建复杂自主智能体。统一多模态标准支持文本、图片、音频输入输出协议标准化跨客户端通用。3. 关键数据流方向反向区别于 ToolTool客户端 AI 主动调用服务端函数Client → ServerSampling服务端主动请求客户端 AI 生成内容Server → Client二、完整标准执行时序5 步完整链路握手声明能力Client 启动连接时在capabilities声明是否支持采样Server 仅当客户端开启sampling能力时才能发送生成请求。json// Client 握手能力声明 { capabilities: { sampling: { tools: true // 支持采样内嵌套工具调用 } } }服务端发起采样请求Server 在 Tool/Resource 回调内部发送 JSON-RPCsampling/createMessage携带对话历史、模型偏好、最大 token 等参数。客户端人机校验VSCode/Claude 弹出弹窗展示完整提示词用户可拒绝本次采样直接返回报错给服务端修改 messages 文本再提交给模型客户端执行 LLM 生成客户端使用自身配置的模型Gemini/Claude执行推理支持工具调用、多轮循环。结果回传给 MCP 服务端客户端将模型输出的完整assistant消息、停止原因、使用的模型名称原路返回给服务端服务端继续完成原有业务逻辑。三、采样请求完整字段规范1. 请求参数sampling/createMessage paramstypescript运行interface SamplingCreateRequest { // 必传多轮对话上下文user/assistant 消息数组支持文本/图片/音频 messages: Array{ role: user | assistant; content: TextContent | ImageContent; }; // 模型偏好给客户端参考选模型 modelPreferences?: { hints?: [{ name: string }]; // 推荐模型名称如 [gemini-1.5-flash] costPriority: number; // 0~1成本最低权重 speedPriority: number; // 0~1速度优先权重 intelligencePriority: number; // 0~1推理能力权重 }; systemPrompt?: string; // 全局系统角色提示词 maxTokens?: number; // 最大生成token上限 temperature?: number; // 随机性 0~1 stopSequences?: string[]; // 停止符 // 进阶采样过程允许LLM调用MCP工具 tools?: ToolDefinition[]; toolChoice?: auto | required | none; }2. 客户端返回结果结构typescript运行interface SamplingCreateResult { model: string; // 实际使用的模型名称 stopReason: endTurn | toolUse | maxToken | stopSequence; content: TextContent | ImageContent; role: assistant; // 固定assistant角色 }3. stopReason 停止原因枚举endTurn模型正常生成结束maxToken到达 maxTokens 截断stopSequence命中停止符toolUse模型需要调用工具服务端需处理工具结果后再次发起采样四、TS MCP 可运行实战代码适配你的用户管理服务场景创建用户时服务端调用客户端 LLM 自动生成用户简介1. 服务端能力声明初始化 Server 时开启采样支持检测typescript运行import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; const server new Server( { name: user-mcp-server, version: 1.0.0 }, { capabilities: {} } // 客户端能力在握手后动态读取 ); // 存储客户端是否支持采样 let clientSupportSampling false; server.oninitialized(() { const clientCap server.getClientCapabilities(); clientSupportSampling !!clientCap.sampling; });2. 在 Tool createUser 内部调用 Sampling核心示例typescript运行// 注册创建用户工具 server.tool( createUser, { name: createUser, description: 新建用户并AI自动生成个人简介, inputSchema: { type: object, required: [name, email, address, phone], properties: { name: { type: string }, email: { type: string }, address: { type: string }, phone: { type: string } } } }, async ({ name, email, address, phone }) { // 1. 先判断客户端是否支持采样不支持则跳过AI生成 let bio 暂无个人简介; if (clientSupportSampling) { try { // 发起采样请求借用客户端LLM生成简介 const samplingResult await server.createMessage({ maxTokens: 128, temperature: 0.6, systemPrompt: 你是用户资料编辑助手根据姓名、地址、联系方式生成简短友好个人简介控制在80字以内, messages: [ { role: user, content: { type: text, text: 姓名${name}联系邮箱${email}居住地址${address}联系电话${phone} } } ], modelPreferences: { intelligencePriority: 0.8, speedPriority: 0.3, costPriority: 0.2 } }); // 提取AI生成文本 bio samplingResult.content.type text ? samplingResult.content.text : bio; } catch (err) { // 用户拒绝采样/客户端报错降级默认简介 bio 简介生成失败暂无资料; } } // 2. 写入users.json你已适配Node20.9 assert语法 const jsonModule await import(./data/users.json, { assert: { type: json } }); const users jsonModule.default; const id users.length 1; users.push({ id, name, email, address, phone, bio }); await fs.writeFile(./src/data/users.json, JSON.stringify(users, null, 2), utf-8); return { content: [{ type: text, text: 创建成功用户ID${id}AI简介${bio} }] }; } );3. 高级采样嵌套 Tool 调用Sampling with Tools如果希望模型生成过程中反过来调用服务端工具在createMessage参数追加tools数组typescript运行await server.createMessage({ messages: [...], tools: [ { name: getAllUsers, description: 读取全部用户数据, inputSchema: { type: object } } ], toolChoice: auto // 模型自主判断是否调用工具 });当返回stopReason: toolUse时服务端解析工具调用、执行函数、拿到结果后再次调用 createMessage把工具结果传给模型继续生成形成完整 Agent 循环。五、四大 MCP 核心原语横向对比Sampling / Tool / Resource / Prompt表格维度Sampling采样Tool工具Resource资源Prompt提示模板数据流方向Server → Client服务端请求客户端 AIClient → ServerAI 主动调用服务端Server → Client服务端只读数据Server → Client服务端下发提示模板触发方服务端代码自动触发嵌套在 Tool/Resource 内客户端 LLM 自主触发AI / 用户手动读取用户手动斜杠命令触发模型归属使用客户端自带 LLM服务端无密钥不消耗模型仅执行本地逻辑纯只读数据无模型调用使用客户端 LLM但由用户手动启动核心用途服务端中途需要 AI 推理、摘要、生成、分类构建嵌套智能体增删改查、外部操作、有副作用业务逻辑静态 / 动态上下文数据源users.json、文档封装标准化工作流提示词代码审查、数据分析人机校验强制弹窗预览用户可拒绝生成仅首次授权后台静默执行无校验直接读取用户主动点击启用无拦截弹窗典型场景创建用户自动生成简介、数据自动分类、文本翻译、内容总结createUser、文件写入、数据库查询、API 请求users://all 用户列表、配置文件、产品文档/code-review一键代码审查模板关键边界区分想让AI 主动操作你的本地文件 / 数据库→ Tool想给 AI 提供只读参考数据→ Resource想给用户提供一键复用的提问模板→ Prompt想在服务端业务执行中途临时调用 AI 做生成 / 推理→ Sampling六、安全与最佳实践1. 安全强制规范必须捕获采样异常用户拒绝、客户端不支持、模型超限都会抛出错误必须 try/catch 做降级处理避免 MCP 进程抛出-32603崩溃敏感上下文过滤采样请求不要携带隐私密钥、手机号明文等高危数据客户端强制人机校验合规客户端VSCode Copilot、Cursor都会弹窗展示完整 prompt无弹窗的客户端存在安全风险。2. 开发最佳实践先检测clientCapabilities.sampling再发起请求兼容不支持采样的旧客户端配置合理maxTokens与temperature控制生成成本与随机性长业务逻辑拆分复杂 Agent 循环工具调用 多次采样分步处理避免单次超大请求降级兜底采样失败时提供静态默认值保证 Tool 业务流程不中断区分modelPreferences权重批量摘要优先 speed深度推理优先 intelligence。3. 常见限制与坑Claude Desktop 早期版本不支持 SamplingVSCode GitHub Copilot、Cursor 完整支持采样无法脱离客户端模型离线无网络时采样请求会直接报错采样内嵌套工具会增加多轮往返复杂循环会提升延迟不要把大量 Resource 超大文本塞进采样 messages会快速耗尽客户端上下文窗口。七、通俗类比理解把 MCP 整套体系比作装修Resource建材仓库只读原材料用户 / AI 随时查看Tool水电工 / 木工AI 主动叫来干活修改房屋状态Prompt标准化装修方案模板业主一键选用整套设计思路Sampling施工队中途需要设计师出效果图 → 施工队Server向业主的设计软件Client LLM请求画图不用施工队自己买设计软件账号业主审批效果图后再继续施工。
