1. 从一次工具调用失败说起MCPSharp 到底解决什么问题如果你正在写 C# 项目想让 AI 助手调用你已有的业务方法比如查订单、算价格、读配置大概率会碰到同一个问题模型能聊天但碰不到你的代码。MCPModel Context Protocol就是为这件事设计的协议它把外部工具和数据源用统一接口暴露给 AI 模型。而 MCPSharp 是 .NET 生态里用来构建 MCP 服务器和客户端的库适合已有 C# 项目、不想手写 JSON-RPC 协议的开发者。我试过一个典型场景本地有个订单查询类想让它被 AI 客户端发现并调用。手写协议要处理请求 ID、参数校验、类型转换、错误码光调试就耗掉半天。换成 MCPSharp 后只需要在方法上加[McpTool]属性启动服务器客户端就能列出工具并调用。整个过程不用碰协议细节。这篇文章按可跟做的路径走先装包、写工具类、配appsettings.json再启动服务器和客户端最后通过 TaoToken 统一 Key 完成一次真实工具调用。中间会给出完整Program.cs骨架、验证命令和常见报错排查。你不需要先理解 MCP 全部规范跟着代码跑通一次再回头看协议会清晰很多。2. TaoToken 前置统一 Key 与 API 通道准备MCPSharp 负责协议层但模型侧需要一个可调用的 API 通道。TaoToken 在这里的角色是统一 Key 和统一入口你不需要为每个模型单独维护一套密钥和地址拿一个 Key 就能在模型对话、编码计划、API 调用之间切换。对 MCP 场景来说客户端拿到工具列表后最终要把工具结果交给模型生成回答这一步走的就是 TaoToken 的 API 通道。先做三件事。第一打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。第二进入控制台创建 API Key地址是 https://taotoken.net/console 。第三如果你打算长期跑编码类 Agent可以顺手看一下 Coding Plan 页面 https://taotoken.net/coding-plan 它更适合持续性的代码生成和工具调用场景。Key 拿到后不要写进代码仓库。推荐用环境变量或用户机密user-secrets注入。下面配置里我会用占位符YOUR_TAOTOKEN_KEY你替换成自己的即可。API 基础地址用 https://taotoken.net/api 注意这个地址不带 UTM 参数直接作为BaseUrl使用。注意MCPSharp 本身不绑定任何模型厂商它只负责把 .NET 方法暴露成 MCP 工具。模型调用走哪条通道由你的客户端配置决定。本文用 TaoToken 作为统一通道是为了让 Key 管理和模型切换更省事。3. 可复制配置appsettings.json 与 Program.cs 骨架3.1 安装包与项目结构新建一个 .NET 8 控制台项目然后安装 MCPSharpdotnet new console -n McpSharpDemo cd McpSharpDemo dotnet add package MCPSharp项目结构建议这样分McpSharpDemo/ Program.cs Tools/OrderTools.cs appsettings.json McpSharpDemo.csprojappsettings.json里放 TaoToken 的通道配置和 MCP 服务器元信息{ TaoToken: { BaseUrl: https://taotoken.net/api, ApiKey: YOUR_TAOTOKEN_KEY, Model: claude-3-5-sonnet }, McpServer: { Name: OrderServer, Version: 1.0.0 } }记得在.csproj里开启 XML 文档生成这样 MCPSharp 能自动提取工具描述PropertyGroup GenerateDocumentationFiletrue/GenerateDocumentationFile NoWarn$(NoWarn);1591/NoWarn /PropertyGroup3.2 用 [McpTool] 暴露一个订单查询方法新建Tools/OrderTools.cs。这里用静态方法加属性标记MCPSharp 启动时会自动扫描基程序集里的[McpTool]using MCPSharp; namespace McpSharpDemo.Tools; /// summary /// 订单相关工具集 /// /summary public class OrderTools { /// summary /// 根据订单号查询订单状态 /// /summary /// param nameorderId订单编号例如 A1001/param /// returns订单状态描述/returns [McpTool(query_order, 根据订单号查询订单状态)] public static string QueryOrder( [McpParameter(true, Description 订单编号)] string orderId) { // 这里替换成你真实的仓储或服务调用 return orderId switch { A1001 已支付预计明天发货, A1002 已发货物流单号 SF123456, _ 未找到该订单 }; } }注意[McpFunction]已经废弃统一用[McpTool]。参数上的[McpParameter(true)]表示必填MCPSharp 会自动做参数校验和类型转换传错类型会返回结构化错误而不是直接抛异常。3.3 Program.cs 启动服务器并注册工具Program.cs负责读配置、注册工具、启动 MCP 服务器using McpSharpDemo.Tools; using MCPSharp; using Microsoft.Extensions.Configuration; var config new ConfigurationBuilder() .AddJsonFile(appsettings.json, optional: false) .AddEnvironmentVariables() .Build(); var serverName config[McpServer:Name] ?? OrderServer; var version config[McpServer:Version] ?? 1.0.0; // 手动注册工具类适合工具放在引用库或需要显式控制的场景 MCPServer.RegisterOrderTools(); // 启动 MCP 服务器走 stdio 与客户端通信 await MCPServer.StartAsync(serverName, version);如果你把工具类放在当前程序集StartAsync会自动扫描放在引用库时用MCPServer.RegisterT()显式注册。两种方式可以混用。3.4 客户端侧连接服务器并拿到 AIFunction客户端用MCPClient连接上面启动的服务器再把工具转成AIFunction列表交给模型调用using MCPSharp; using Microsoft.Extensions.AI; var client new MCPClient( name: TaoTokenClient, version: 1.0, server: dotnet, args: run --project ./McpSharpDemo.csproj ); IListAIFunction functions await client.GetFunctionsAsync(); // 调用一次工具验证链路 var result await client.CallToolAsync( query_order, new Dictionarystring, object { { orderId, A1001 } } ); Console.WriteLine($工具返回{result});GetFunctionsAsync()返回的列表可以直接塞进ChatOptions.Tools配合任何IChatClient实现使用。这样模型在对话中就能自主决定是否调用query_order。4. 验证请求跑通一次真实工具调用4.1 先单独验证服务器能列出工具打开一个终端启动服务器dotnet run --project ./McpSharpDemo.csproj服务器走 stdio不会在控制台打印花哨日志这是正常的。另开一个终端用客户端脚本连接并列出工具var tools await client.GetToolsAsync(); foreach (var tool in tools) { Console.WriteLine(${tool.Name} - {tool.Description}); }预期输出query_order - 根据订单号查询订单状态如果这里能看到工具名和描述说明 MCPSharp 的扫描和注册已经生效。4.2 通过 TaoToken 通道完成模型侧调用工具能列出之后把AIFunction列表交给模型。下面用 TaoToken 的 API 地址和 Key 构造客户端配置var taoTokenKey config[TaoToken:ApiKey]; var baseUrl config[TaoToken:BaseUrl]; var model config[TaoToken:Model]; // 伪代码示意把 functions 注入 ChatOptions var options new ChatOptions { Tools functions.CastAITool().ToList() }; // 模型收到用户问题后会决定是否调用 query_order // 调用结果再回传给模型生成最终回答实际跑的时候用户问“A1001 发货了吗”模型会触发query_orderMCPSharp 执行你的 C# 方法返回“已支付预计明天发货”模型再把这个结果组织成自然语言。整条链路里TaoToken 负责模型侧的 Key 和通道MCPSharp 负责工具侧的协议和调用。4.3 成功结果长什么样一次成功的调用会看到三段信息客户端发出tools/call请求、服务器返回结构化结果、模型基于结果生成回答。如果你在CallToolAsync后打印result应该看到类似已支付预计明天发货到这里MCP 服务器、客户端、TaoToken 通道三者已经串通。你可以把QueryOrder换成真实的数据库查询或 HTTP 调用协议层不用改。5. 本篇常见错排查5.1 工具列表为空最常见的原因是工具类没有被扫描到。检查两点方法是否标记了[McpTool]以及类是否在基程序集或已通过MCPServer.RegisterT()注册。如果工具在引用库自动扫描不会覆盖必须显式注册。另外确认GenerateDocumentationFile已开启否则描述可能为空。5.2 参数校验失败或类型不匹配MCPSharp 会自动做类型转换但前提是客户端传的参数名和[McpParameter]对应。比如orderId写成order_id就会找不到。必填参数没传时服务器返回结构化错误而不是崩溃你可以在客户端捕获后提示用户补参数。5.3 客户端连接服务器超时MCPClient的server和args要能正确拉起服务器进程。上面示例用dotnet run --project如果你已经发布成可执行文件改成对应路径。路径里有空格时注意引号。另外服务器走 stdio不要在里面写Console.ReadLine()之类会阻塞标准输入的逻辑。5.4 TaoToken 侧返回 401 或 403先确认 Key 是否复制完整有没有多余空格。然后检查BaseUrl是否写成https://taotoken.net/api不要带 UTM 参数。如果 Key 是在控制台新建的确认它没有被禁用或删除。需要重新生成时去 https://taotoken.net/api-keys 操作。5.5 模型不调用工具模型是否调用工具取决于工具描述和用户问题的匹配度。把[McpTool]的 Description 写清楚参数描述也补上。如果模型仍然不调用可以在系统提示里明确要求“需要订单信息时调用 query_order”。另外确认functions确实传进了ChatOptions.Tools空列表模型无从调用。6. 接下来怎么走按场景选通道如果你只是验证模型能不能正确调用工具直接打开模型对话页面 https://taotoken.net/model-chat 试几轮把工具描述贴进去看模型反应比写完整客户端更快。如果你要把 MCP 工具接入现有 .NET 项目重点看接入文档 https://taotoken.net/doc 里面有 Key 注入和通道配置的细节。如果你打算长期跑编码类 Agent工具调用会非常频繁Coding Plan https://taotoken.net/coding-plan 在配额和通道稳定性上更适合持续使用。MCPSharp 的价值在于把协议细节收进库内部你只需要关心业务方法本身。我踩过的坑是过早去读 JSON-RPC 规范其实先把一个[McpTool]跑通再回头看协议会省很多时间。你可以从QueryOrder开始换成自己项目里最常用的那个方法跑通一次调用后面扩展就是复制粘贴加属性的事。