1. 为什么 .NET 10 的 dnx nuget 让 MCP 服务分发变简单了如果你最近在折腾 AI 工具链大概率听过 MCPModel Context Protocol这个词。简单说它是一套让大模型能调用外部工具和数据的标准协议你可以把它理解成「AI 世界的 USB 接口」——只要服务端按协议暴露工具客户端就能即插即用。过去写 MCP 服务Python 圈有 uvx、Node 圈有 npx一条命令就能把服务拉起来跑而 .NET 开发者只能自己 dotnet run 或者手动编译分发和消费都挺别扭。.NET 10 预览版把这块短板补上了。核心是两件事一是 NuGet.org 开始支持托管和消费用 ModelContextProtocol C# SDK 构建的 MCP 服务器包类型标记为 mcpserver等于把 NuGet 从「库包仓库」升级成了「可发现、可版本化的 AI 服务分发平台」二是引入了 dnx 工具执行脚本配合 C# MCP 服务实现了类似 uvx / npx 的本地快速启动能力。换句话说C# 开发者现在也能一条命令拉起一个 AI 服务来开发和测试。这套组合适合谁我梳理了三类第一类是 .NET 后端开发者想把现有业务能力包装成 MCP 工具给 AI 客户端调用第二类是工具链维护者希望把自己的 CLI 或服务以标准包形式分发第三类是 AI 应用集成方需要在 VS Code、Cherry Studio 这类客户端里挂载本地 MCP 服务。本文会从项目初始化、工具编写、打包发布一直讲到用 TaoToken 统一 Key 打通调用链每一步都给可复制的命令和配置。需要提前说明的是MCP 服务本身只负责「暴露工具」真正让大模型理解并调用这些工具还需要一个能访问模型的通道。这就是后面要引入 TaoToken 的原因——它提供统一的 API 入口和 Key 管理让你不用在多个模型供应商之间来回切换配置。下面先从环境准备开始。2. TaoToken 前置准备统一 Key 与 API 通道怎么配在动手写 MCP 服务之前先把模型调用这条链路准备好。很多同学卡在第一步MCP 服务写完了客户端也挂上了但模型侧没有可用的 Key或者 Key 散落在好几个平台换一个模型就要改一次配置。TaoToken 的思路是提供一个统一的 API 通道你只需要维护一个 Key就能访问多种模型。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 完成账号注册后进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面可以创建新的 Key。创建时建议给 Key 起一个能区分用途的名字比如 mcp-dotnet-dev方便后面排查问题时定位。拿到 Key 之后你需要记住两个地址API 基础地址是 https://taotoken.net/api 这个地址不带任何查询参数直接作为 Base URL 使用模型对话的入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 你可以在那里先手动试一次对话确认 Key 可用。这一步很关键因为后面 MCP 服务调用失败时你需要快速判断是服务端问题还是 Key 问题。关于模型 IDTaoToken 的接口兼容主流格式你在请求体里填的 model 字段就是模型标识。建议先在模型对话页面确认你要用的模型 ID 拼写比如常见的 claude 系列或 gpt 系列不同模型的 ID 大小写和连字符都不一样填错了会直接返回错误。我试过把模型 ID 写错一个字母结果排查了半小时才发现是拼写问题所以这一步别偷懒。如果你打算长期做编码类或 Agent 类开发可以关注 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合高频调用场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有完整的请求示例和参数说明。API Keys 管理页再贴一次https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 后面配置环境变量时会用到。把 Key 存到环境变量里不要硬编码进代码。Windows 下可以用 setxmacOS / Linux 下写进 shell 配置文件# macOS / Linux写入 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api# Windows PowerShell设置用户级环境变量 [Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User) [Environment]::SetEnvironmentVariable(TAOTOKEN_BASE_URL, https://taotoken.net/api, User)设置完记得重开终端或者手动 source 一下配置文件否则当前会话读不到新变量。验证是否生效echo $TAOTOKEN_API_KEY # 应该输出你的 Key而不是空行这一步做完模型通道就准备好了。接下来进入正题用 .NET 10 的模板创建 MCP 服务项目。3. 可复制配置从 dotnet new mcpserver 到打包发布先确认你的 SDK 版本。dnx 和 mcpserver 模板都需要 .NET 10 预览版 SDK用下面的命令检查dotnet --version # 期望输出 10.0.100-preview.x 或更高如果版本不对去 .NET 官网下载对应预览版 SDK。装好之后安装 AI 模板包dotnet new install Microsoft.Extensions.AI.Templates安装成功会列出可用模板其中 mcpserver 就是我们要用的。创建项目dotnet new mcpserver -n SampleMcpServer cd SampleMcpServer生成的项目结构里Program.cs 是入口Tools 目录放工具类.mcp/server.json 是服务清单。先看 Program.cs 里的配置链它做了三件事AddMcpServer() 注册 MCP 服务WithStdioServerTransport() 指定用标准输入输出通信本地工具首选WithTools() 挂载具体工具。默认会带一个 RandomNumberTools我们再加一个天气工具。在 Tools 目录下新建 WeatherTools.csusing System.ComponentModel; using ModelContextProtocol.Server; namespace SampleMcpServer.Tools; [McpServerToolType] public class WeatherTools { [McpServerTool] [Description(Describes random weather in the provided city.)] public string GetCityWeather( [Description(Name of the city to return weather for)] string city) { var weather Environment.GetEnvironmentVariable(WEATHER_CHOICES); if (string.IsNullOrWhiteSpace(weather)) { weather balmy,rainy,stormy; } var weatherChoices weather.Split(,); var selectedWeatherIndex Random.Shared.Next(0, weatherChoices.Length); return $The weather in {city} is {weatherChoices[selectedWeatherIndex]}.; } }这里有几个要点[McpServerToolType] 标记这个类是工具容器[McpServerTool] 把方法暴露成工具[Description] 是给大模型看的自然语言说明——它直接决定模型能不能正确调用你的工具所以描述要写清楚参数含义。然后在 Program.cs 里注册这个工具类builder.Services .AddMcpServer() .WithStdioServerTransport() .WithToolsRandomNumberTools() .WithToolsWeatherTools(); await builder.Build().RunAsync();接下来配置打包。打开 .csproj确保包含这几个属性PropertyGroup TargetFrameworknet10.0/TargetFramework PackAsTooltrue/PackAsTool PackageTypeMcpServer/PackageType PackageIdyourname.SampleMcpServer/PackageId PackageVersion0.2.0/PackageVersion ToolCommandNamesample-mcp-server/ToolCommandName /PropertyGroupPackAsTool 让它成为标准 .NET 工具包PackageType 标记为 McpServer 让 NuGet.org 能识别并生成配置说明ToolCommandName 是 dnx 调用时的命令名。然后更新 .mcp/server.json让 name 和 version 与包信息一致{ description: 一个带有天气和随机数工具的示例MCP服务器, name: io.github.yourname/SampleMcpServer, packages: [ { registry_name: nuget, name: yourname.SampleMcpServer, version: 0.2.0, package_arguments: [], environment_variables: [ { name: WEATHER_CHOICES, description: 以逗号分隔的天气描述列表, is_required: true, is_secret: false } ] } ], repository: { url: https://github.com/yourname/SampleMcpServer, source: github }, version_detail: { version: 0.2.0 } }这个清单文件的作用是让客户端在首次使用时自动提示用户配置环境变量实现无缝设置。打包命令dotnet pack -c Release生成的 .nupkg 在 bin/Release 目录下上传到 NuGet.org 即可。上传后包页面会自动生成 MCP Server 配置说明别人搜索 mcpserver 类型就能发现你的服务。4. 验证请求dnx 启动服务并用 TaoToken 核对返回结果包发布后本地先用 dnx 验证能不能跑起来dnx yourname.SampleMcpServer0.2.0 --yes--yes 表示跳过确认直接执行。如果服务正常它会等待 stdio 输入说明 MCP 服务已经就绪。这一步能跑通说明打包和清单配置都没问题。接下来在客户端里挂载。以 VS Code 为例在项目目录下创建 .vscode/mcp.json{ servers: { SampleMcpServer: { type: stdio, command: dnx, args: [ yourname.SampleMcpServer0.2.0, --yes ], env: { WEATHER_CHOICES: sunny,humid,freezing,perfect } } } }用 VS Code 打开项目在 Copilot 里问「北京今天天气如何」如果工具被正确调用你会看到它返回类似「The weather in 北京 is sunny.」的结果。这说明 MCP 服务端和客户端之间的 stdio 通道是通的。现在验证模型调用链路。MCP 服务本身不访问模型它只暴露工具真正决定调用哪个工具的是模型。所以你需要一个能访问模型的通道这里用 TaoToken。写一个简单的验证脚本用 curl 发一次请求curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [ {role: user, content: 你好请回复一句话确认通道正常} ] }如果返回里有 choices 数组且 content 有内容说明 Key 和通道都正常。这一步的意义在于当 MCP 客户端调用模型失败时你可以先用这个 curl 快速判断是模型通道问题还是 MCP 配置问题。我踩过的坑就是 MCP 配置全对但 Key 过期了结果一直在查服务端浪费了不少时间。把两者串起来MCP 客户端负责把工具列表发给模型模型决定调用哪个工具工具执行结果再回传给模型生成最终回答。TaoToken 在这里的角色是提供模型访问能力你只需要在客户端里配置一次 Base URL 和 Key不用为每个模型单独配。模型对话入口再贴一次方便你测试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。5. 本篇常见错排查401、local proxy failed、reading choices 怎么解第一个高频错误是 401 Unauthorized。报错长这样{error: {message: Invalid API key, type: authentication_error}}原因通常是 Key 没读到或者写错了。排查顺序先 echo $TAOTOKEN_API_KEY 确认环境变量有值再确认请求头是 Authorization: Bearer 加空格加 Key少个空格也会 401最后确认 Key 没有过期或被删除。如果是在 MCP 客户端里报 401检查客户端的 env 配置有没有把 Key 传进去有些客户端不会自动继承系统环境变量。第二个是 local proxy failed 或连接被拒绝。这类报错一般出现在客户端尝试连接本地 MCP 服务时Error: local proxy failed to connect to stdio server原因通常是 dnx 命令路径不对或者包名版本写错。排查先在终端手动跑一遍 dnx yourname.SampleMcpServer0.2.0 --yes确认能启动再检查 mcp.json 里的 command 是不是 dnx 的完整路径有些环境需要写绝对路径最后确认 args 里的包名和版本与 NuGet 上发布的一致。如果包还没发布到 NuGetdnx 是拉不到的本地测试可以先用 dotnet run --project . 代替。第三个是 reading choices 相关报错比如Error: reading choices: unexpected end of JSON input这通常发生在模型返回体解析阶段说明请求发出去了但返回不是预期的 JSON。可能原因Base URL 写成了 https://taotoken.net/api/ 带了尾部斜杠导致路径拼接错误正确写法是不带斜杠的 https://taotoken.net/api 或者模型 ID 填错服务端返回了错误页而不是 JSON。排查方法是用第 4 节的 curl 命令单独测一次看返回体到底是什么。第四个是 OAuth 相关报错比如Error: OAuth token exchange failed如果你用的是 Claude Code 这类需要 OAuth 的客户端检查是不是把 API Key 和 OAuth 流程搞混了。API Key 方式直接填 Key 就行不需要走 OAuth。如果客户端强制走 OAuth确认你的账号状态正常必要时重新生成 Key。接入文档里有各客户端的配置示例地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后提醒一个容易忽略的点MCP 服务的 server.json 里声明的环境变量如果标记了 is_required: true客户端在首次使用时会提示配置。如果你在 mcp.json 里没提供这个变量工具执行时读到空值可能返回不符合预期的结果。建议在工具代码里对空值做兜底就像 WeatherTools 里那样给个默认值。6. 把 MCP 服务接入长期编码流Coding Plan 与统一 Key 的配合前面走完了一遍完整的「开发—打包—发布—调用」流程但如果你打算把 MCP 服务用在日常编码或 Agent 场景里还有几个实践建议。第一把常用工具拆成独立的 MCP 服务包而不是全塞在一个项目里。比如数据库查询、文件操作、API 调用各做一个包这样客户端可以按需挂载启动更快也更容易版本管理。每个包用独立的 PackageId 和 ToolCommandName避免冲突。第二统一 Key 管理。当你有多个 MCP 服务都需要访问模型时如果每个服务各自配 Key维护成本会很高。用 TaoToken 的统一 Key所有服务共用一套 Base URL 和 Key换模型只需要改 model 字段不用动 Key。Coding Plan 地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合调用频率高的场景。第三版本发布要规范。每次改工具逻辑或参数描述都要升 PackageVersion并同步更新 server.json 里的 version。因为客户端可能缓存了旧版本版本号不变的话 dnx 不会重新拉取。建议用语义化版本工具描述变更算 minor破坏性变更算 major。第四测试时先用 dnx 本地跑通再挂到客户端。dnx 的好处是它直接从 NuGet 拉包执行和客户端的行为一致能提前暴露包配置问题。如果 dnx 跑不起来客户端大概率也跑不起来。最后如果你在接入过程中遇到报错优先用 curl 单独测模型通道确认 Key 和 Base URL 没问题再去查 MCP 服务端配置。这个排查顺序能帮你快速定位问题在哪一层。API Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 需要时直接查。