.NET MCP 服务端 Sampling 权威指南：基于 ModelContextProtocol 2.x 通过客户端调用 LLM 的完整方案-北京尧图网络

.NET MCP 服务端 Sampling 权威指南基于 ModelContextProtocol 2.x 通过客户端调用 LLM 的完整方案【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot导读本文是 awesome-copilot 仓库中 dotnet-mcp-builder 技能参考文档references/sampling.md的深度展开聚焦 .NET MCP 服务端基于官方ModelContextProtocol2.x NuGet 包如何通过Sampling机制借用客户端已配置的 LLMClaude、GPT、本地模型等完成摘要、分类、起草、抽取等 AI 步骤。读完本文你将掌握 sampling 的适用场景与弃用现状、两种调用 APIIChatClient适配器与底层SampleAsync的完整写法、ModelPreferences与IncludeContext的调参技巧、能力探测与降级策略以及 sampling 与服务端直连模型两种路线的取舍决策。重要版本前提当前仓库的 SKILL.md 明确该技能面向stable 2.x包与2026-07-28 版 MCP 规范。Sampling 已在该规范中弃用SDK 2.x 将 sampling API 标记为[Obsolete]构建警告MCP9005。本文全部代码示例以仓库文档为准面向维护 1.x 时代存量服务端的使用者而非新服务器设计者。一、Sampling 是什么让服务端借客户的模型Sampling 允许 MCP 服务端tool通过客户端调用 LLM而不是自己内置模型。服务端只需要说帮我把这段内容总结一下客户端就会把请求路由到用户已配置的模型Claude、GPT、本地模型任何模型均可。由此带来一个关键特性成本与速率限制归属于客户端而不是服务端——用户使用自己的 API Key 与配额服务端不接触任何密钥。这一机制与仓库中 elicitation.md 讲解的 elicitation服务端通过客户端向用户提问同属服务端→客户端回调类能力都依赖有状态的传输通道不同的是 elicitation 的目标是用户sampling 的目标是模型。何时应该使用 sampling原文档给出三条明确的适用判据工具需要一个 LLM 步骤摘要、分类、起草、抽取而你不想在服务端自行搭载/配置模型你希望尊重用户的模型选择、密钥与成本偏好你在构建元工具meta toolLLM 编排是其职责的一部分例如多步骤 Agent。同时有一条硬性红线如果你已经有确定性的算法不要为了风味硬加一次 sampling 调用——它只会增加延迟与成本。弃用状态与替代方案2026-07-28 规范原文档开篇的警示框是本文最重要的背景SDK 2.x 已将 sampling API 标记为[Obsolete]构建时产生MCP9005警告过渡期内它们仍与低版本客户端保持 wire 兼容但不要围绕 sampling 设计新服务器工具执行中需要用户/LLM 输入的正确新姿势是多轮往返input_required模式详见 elicitation.md 中的InputRequiredException/InputRequest.ForElicitation(...)说明服务端需要 LLM的正确新姿势是服务端直接调用模型仅将本页用于维护 1.x 时代存量服务端MCP9005警告只允许作为有记录的过渡措施被抑制。这与 SKILL.md 中Cardinal rules第 5 条完全一致2026-07-28 规范弃用 roots、sampling 与 MCP-channel 日志SDK 标记[Obsolete]MCP9005它们对低版本客户端仍然可用但新设计应改用多轮input_required模式与ILogger日志。前置条件有状态的传输通道与 elicitation 一样sampling 需要服务端回调客户端并等待响应因此对传输方式有硬性要求STDIO始终可用进程内双向管道天然支持回调HTTPStreamable必须设置options.Stateless false。注意在 2.x 中 HTTP 默认是无状态Stateless true这是 v2 最重要的破坏性变更之一见 transport-http.md。而 2026-07-28 现行规范已取消 HTTP 会话设置Stateless false会让服务器拒绝该规范版本改为通过低版本initialize回退服务客户端。因此 sampling以及ElicitAsync、roots在现行协议的 HTTP 上根本无法运行——这正是官方把 sampling 弃用的底层原因传输通道已经不存在了。二、推荐写法IChatClient适配器原文档给出的最优雅 API是把 sampling 通道包装为Microsoft.Extensions.AI.IChatClient让服务端代码看起来就像普通 .NET 应用调用 LLM 一样。完整示例using System.ComponentModel; using Microsoft.Extensions.AI; using ModelContextProtocol.Server; [McpServerToolType] public class SummaryTools { [McpServerTool(Name SummarizeContent), Description(Summarises arbitrary text using the clients LLM.)] public static async Taskstring Summarize( IMcpServer server, [Description(The text to summarize)] string text, CancellationToken cancellationToken) { ChatMessage[] messages [ new(ChatRole.User, Briefly summarize the following content:), new(ChatRole.User, text), ]; var options new ChatOptions { MaxOutputTokens 256, Temperature 0.3f, }; var response await server.AsSamplingChatClient() .GetResponseAsync(messages, options, cancellationToken); return $Summary: {response}; } }该写法的三点优势原文档原文要点API 一致性与 .NET AI 生态其他部分使用相同的IChatClient接口中间件兼容可无缝配合Microsoft.Extensions.AI中间件限流、重试、遥测、函数调用——这些能力在仓库 packages.md 的Optional but commonly useful表格中被明确列出Microsoft.Extensions.AI提供IChatClient、ChatMessage、ChatRole、ChatOptions正是AsSamplingChatClient()所依赖的抽象可测试性测试时注入不同的IChatClient即可切换为直接调用真实 Provider服务端代码无需改动。从 SDK 注册结构看见 SKILL.md 的 30 秒心智模型AsSamplingChatClient()与ElicitAsync、进度通知等同属于服务端到客户端特性都是挂在注入的IMcpServer实例上的方法这与示例中IMcpServer server参数的注入方式完全对应。三、底层写法SampleAsync全参数控制当需要完全控制请求形态时使用底层SampleAsync。原文档完整示例using ModelContextProtocol.Protocol; CreateMessageResult result await server.SampleAsync( new CreateMessageRequestParams { Messages [ new SamplingMessage { Role Role.User, Content [new TextContentBlock { Text What is 2 2? }] } ], MaxTokens 100, Temperature 0.0f, SystemPrompt You are a precise calculator., // ModelPreferences, StopSequences, IncludeContext... }, cancellationToken); string answer result.Content .OfTypeTextContentBlock() .FirstOrDefault()?.Text ?? string.Empty;参数要点说明参数作用备注Messages发送给模型的对话消息SamplingMessage含Role与ContentRole使用ModelContextProtocol.Protocol.Role枚举MaxTokens输出 token 上限与成本直接相关应保守设置Temperature采样温度确定性任务可设为0.0fSystemPrompt系统提示词如示例中你是一个精确的计算器ModelPreferences模型选择偏好提示仅作为提示最终由客户端决定实际模型StopSequences停止序列可选IncludeContext是否携带当前对话上下文见第五节注意result.Content是内容块集合需要OfTypeTextContentBlock()过滤文本块再取.Text——这与仓库 client.md 中客户端侧解析CallToolResult.Content的TextContentBlock/ImageContentBlock模式是一致的MCP 的内容一律以 block 列表形态承载。ModelPreferences软性模型选择提示ModelPreferences允许服务端提示模型选择成本/速度/智能优先级但最终选择权在客户端。原文档示例ModelPreferences new ModelPreferences { Hints [new ModelHint { Name claude }], // soft preference CostPriority 0.2, // 0..1 SpeedPriority 0.4, IntelligencePriority 0.9, }Hints一组软偏好提示如首选claude客户端可采纳也可忽略CostPriority/SpeedPriority/IntelligencePriority三个取值 0..1 的优先级权重表达服务端对省钱 / 快 / 聪明的权衡倾向。注意示例中三者并非强制归一化0.20.40.91它们只是相对权重信号。四、IncludeContext借用当前会话上下文Sampling 请求可以要求客户端附带当前对话的上下文避免服务端重复供给历史IncludeContext ContextInclusion.ThisServer // include this servers prior messages // or AllServers, or None (default)三个取值ThisServer附带本服务端此前的消息AllServers附带所有服务器的消息None默认不附带。原文档指出其典型用途当你需要 LLM 考虑聊天中已发生的内容又不想自己重新喂一遍时该参数非常有用。五、能力检查不要盲调用许多客户端并不支持 sampling因此调用前必须验证客户端能力。原文档给出的防御式检查if (server.ClientCapabilities?.Sampling is null) throw new McpException( This client does not support sampling. Configure a model in the host or use a different MCP client.);这与仓库中 elicitation 的客户端能力检查server.ClientCapabilities?.Elicitation is null以及 server-features.md 中Roots 和 sampling 是客户端能力服务器从不广告它们只在使用同样被弃用的客户端侧特性前检查server.ClientCapabilities?.Roots/.Sampling的说明完全一致。sampling 属于客户端广告的能力服务端只能被动检查。另外从客户端视角client.md若服务端使用 sampling客户端必须在McpClientOptions.Capabilities.Sampling.SamplingHandler中提供处理函数把req.Messages路由到自己的IChatClient并返回CreateMessageResult如果客户端不提供该 handler 而服务端调用了该特性调用会以 method not supported 失败。这正是上述能力检查存在的意义。六、性能与成本注意事项原文档明确列出的三条性能纪律网络往返是常态sampling 调用是服务端 → 客户端 → 模型服务商 → 回来的完整网络链路耗时通常在100ms 到数秒之间。不要在循环中紧耦合地调用token 成本由用户承担费用记在用户的 API Key / 配额上因此MaxTokens必须保守设置避免浪费用户的钱取消会传播用户中止工具调用时sampling 请求也会随之取消CancellationToken贯穿全链路。对测试与调试而言仓库 testing.md 提供了关键实践sampling 在 2.x 已弃用测试项目会出现MCP9005警告若刻意覆盖旧路径可在测试 csproj 中抑制测试时通过内存传输InMemoryTransport/StreamServerTransport/StreamClientTransport把真实服务端与真实客户端接在同一进程内并在客户端注册确定性 mock 的SamplingHandler返回MOCK SUMMARY之类的固定CreateMessageResult即可让工具中的server.SampleAsync命中可预测的桩实现无 LLM、无网络的集成测试。[McpServerTool]特性不影响 MCP 接线之外的运行时行为——你的方法就是普通方法这也让纯逻辑单元测试变得非常简单。七、Sampling vs 服务端直连模型决策对比原文档给出了一张关键对比表直接决定架构选型Sampling经由客户端直接 LLM 调用服务端侧使用用户的模型 Key使用你的服务 Key尊重用户的策略/配额计费/跟踪是你的责任在用户拥有的任何宿主中都能工作被锁定在你随服务搭载的模型上延迟更高多一跳延迟更低、更直接无需管理密钥你需要管理 API Key选型结论原文档原意面向大量用户的智能服务器优先 sampling——用户的模型、密钥与策略天然被尊重服务端零密钥管理负担内部企业服务器若需要行为一致且你已在为模型付费直连也完全可以。八、写在最后迁移路线图结合仓库 SKILL.md 的决策树与故障排查清单给出存量 sampling 服务端的迁移与维护建议新项目一律不用 sampling需要 LLM 步骤就用IChatClient直连服务端自持密钥需要用户输入就用多轮input_required模式见 elicitation.md存量 1.x 服务端维护保留本页代码模式MCP9005警告仅作有记录的过渡措施抑制并在代码注释/README 中说明弃用原因传输层约束STDIO 始终可用若必须用 HTTPStateless false会把客户端钉死在低版本initialize修订上详见 transport-http.md 的 Stateless vs Stateful 表格需在部署文档中明示这一兼容代价客户端互操作确保客户端侧配置SamplingHandler见 client.md否则调用会以 method not supported 失败测试降级用 testing.md 的内存传输 mockSamplingHandler模式覆盖旧路径保持 CI 可在纯dotnet test环境下运行无需 Node、无需 Docker。延伸阅读本技能其余参考文档可在仓库中直接查阅——packages.md包与目标框架、transport-stdio.md 与 transport-http.md传输层、elicitation.md多轮交互替代方案、client.md客户端 handler 接线、testing.md测试与调试、server-features.md能力广告与客户端能力检查。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

.NET MCP 服务端 Sampling 权威指南：基于 ModelContextProtocol 2.x 通过客户端调用 LLM 的完整方案

相关推荐

24G 显卡能训自己的视频风格吗？CogVideoX LoRA 微调完整指南

Archon 工作流节点级 MCP 服务器接入指南：为 DAG 节点按需挂载外部工具

Jenkins 如何设置代理的 of executors 并发数，并用 0 临时下线代理？

更多资讯

Pydantic Evals 第三方评测框架集成：把 Ragas 与 DeepEval 指标封装为自定义 Evaluator

SkillSpector Multilingual Batch Scanner 实战指南：目录并行扫描、语言检测与 LLM Gap-Fill 原理

YOLOv3+PyQt5交通路口智能监控系统实现

NeMo Speech 开源协作实战：从 PR 规范、测试与 CI 到代码风格与命名约定

Cua Driver 与 Lume 的持久化发布渠道选择机制：RFC 3101 设计与实现全解析

UnoCSS Autocomplete 引擎详解：@unocss/autocomplete 的模板 DSL、建议生成流程与 IDE 集成原理

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？