手把手带你用BotSharp + MCP 三步实现智能体开发：TaoToken统一Key接入与配置验证

1. 为什么要在 BotSharp 里接 MCP以及模型通道怎么选BotSharp 是一个 .NET 生态里的智能体Agent开发框架它把对话管理、意图识别、函数调用、插件编排这些能力都封装好了你只要写业务逻辑就能拼出一个能干活儿的智能体。而 MCPModel Context Protocol模型上下文协议解决的则是另一个问题让大模型用统一的方式去连接外部工具和数据源。你可以把 MCP 理解成 AI 世界的 USB-C 接口不管对面是查价格的接口、下单的服务还是读写文件的工具只要按 MCP 协议暴露出来模型就能即插即用不用为每个工具单独写一套集成代码。把这两个东西放一起价值就很直接了BotSharp 负责智能体的“大脑调度”MCP 负责“手脚扩展”。你写一个 MCP Server 把披萨价格查询、下单、支付三个工具暴露出去BotSharp 里的 Order 智能体就能通过 MCP 客户端自动发现并调用这些工具整个过程不需要你手写 function calling 的 JSON Schema。但真正动手时很多人会卡在第一步——模型通道。BotSharp 要调用大模型就得配 API Key、Base URL、模型名。如果你同时用几家模型或者团队里多人共用Key 管理会变得很乱。这篇要讲的 TaoToken 就是来解决这个问题的它提供一个统一的 Key 和 API 通道OpenAI 兼容格式BotSharp 里改一个 Base URL 就能接上不用为每个模型供应商单独维护配置。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。这篇适合谁如果你是会 .NET、想快速跑通一个 BotSharp MCP 智能体 demo 的开发者或者你已经在用 BotSharp 但被多模型 Key 管理烦到那接下来的三步操作清单和可复制配置就是给你准备的。我会给出 config.toml 和 settings.json 的骨架、三步操作、连通性验证动作以及几个我实际踩过的报错排查点。2. 前置准备TaoToken 统一 Key 与 BotSharp 环境在写任何 MCP 代码之前先把模型通道打通。这一步不做后面智能体跑起来也是空转。2.1 拿到 TaoToken 的 Key 和 API 地址先去控制台创建一个 API Key。入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完你会拿到一串以 sk- 开头的 Key复制保存好后面配置里要用。API 的基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为 Base URL 填进去就行。它兼容 OpenAI 的接口格式所以 BotSharp 里凡是走 OpenAI 协议的地方把 Base URL 换掉即可。如果你还没决定用哪个模型可以先去模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。选一个你熟悉的模型名比如 gpt-4o 或 claude 系列记下准确的模型标识配置里要一字不差。2.2 BotSharp 项目环境你需要一个能跑的 BotSharp 项目。如果你还没有最快的办法是克隆官方示例仓库或者用 dotnet new 建一个 WebAPI 项目再引入 BotSharp 的 NuGet 包。核心包包括 BotSharp.Core、BotSharp.Plugin.OpenAI或对应的模型插件、BotSharp.Core.MCP。MCP 集成模块目前已经能把 MCP Server 的 Tools 注册成 BotSharp 的 IFunctionCallback这是后面智能体能调用工具的关键。环境要求.NET 8.0 SDK、能访问外网用于拉 NuGet 包和调用模型 API。MCP Server 那边我们用一个独立的 ASP.NET Core 项目来承载通过 SSE 传输和 BotSharp 通信。2.3 三步操作清单总览整个流程压缩成三步你先有个全局印象第一步配好 TaoToken 的 Key 和 Base URL让 BotSharp 能调通模型。第二步起一个 MCP Server把工具暴露出来并用 Inspector 验证工具能被发现。第三步在 BotSharp 里配置 MCP Server 地址把工具挂到智能体上发一条消息验证端到端跑通。下面每一部分都给可复制的配置和命令。3. 可复制配置config.toml 与 settings.json 骨架BotSharp 的配置分两块模型通道配置和 MCP 客户端配置。不同版本的 BotSharp 配置文件格式略有差异有的用 appsettings.json有的用 config.toml。我把两种骨架都给你按你项目实际用的格式选。3.1 模型通道配置TaoToken 接入如果你用的是 appsettings.json 风格的配置模型部分大概长这样{ LlmProviders: [ { Provider: openai, Models: [ { Name: gpt-4o, ApiKey: sk-你的TaoTokenKey, Endpoint: https://taotoken.net/api, Type: chat } ] } ] }关键点就两个Endpoint 填 https://taotoken.net/api ApiKey 填你在控制台创建的那串 Key。Provider 保持 openai因为 TaoToken 走的是 OpenAI 兼容协议BotSharp 的 OpenAI 插件能直接识别。如果你用的是 config.toml 风格等价写法是[[LlmProviders]] Provider openai [[LlmProviders.Models]] Name gpt-4o ApiKey sk-你的TaoTokenKey Endpoint https://taotoken.net/api Type chat注意 Endpoint 后面不要加 /v1 或 /chat/completionsBotSharp 的插件会自己拼路径。加了反而会 404。这是我最开始踩的坑后面排错部分会细说。3.2 MCP 客户端配置MCP 的配置放在 BotSharp 的 settings.json 里结构如下{ MCP: { Enabled: true, McpClientOptions: { ClientInfo: { Name: SimpleToolsBotsharp, Version: 1.0.0 } }, McpServerConfigs: [ { Id: PizzaServer, Name: PizzaServer, TransportType: sse, TransportOptions: [], Location: http://localhost:58905/sse } ] } }McpServerConfigs 是一个数组意味着你可以同时挂多个 MCP Server。每个 Server 用 Id 和 Name 标识TransportType 填 sseLocation 填你 MCP Server 实际监听的 SSE 地址。端口号要和你 MCP Server 项目启动时一致不一致就连不上。3.3 MCP Server 端的工具注册配置MCP Server 那边用 MCP C# SDK 注册工具。先装两个 NuGet 包PackageReference IncludeModelContextProtocol / PackageReference IncludeModelContextProtocol.AspNetCore /然后在 Program.cs 里启动 MCP Servervar builder WebApplication.CreateBuilder(args); builder.Services.AddMcpServer() .WithToolsFromAssembly(); var app builder.Build(); app.MapGet(/, () MCP Pizza Server is running.); app.MapMcp(); app.Run();WithToolsFromAssembly 会扫描程序集里所有标了 McpServerToolType 的类把里面的 McpServerTool 方法注册成可被调用的工具。你不需要手动一个个注册。工具类本身长这样以支付工具为例using ModelContextProtocol.Server; using System.ComponentModel; using System.ComponentModel.DataAnnotations; namespace BotSharp.PizzaBot.MCPServer.Tools; [McpServerToolType] public static class MakePayment { [McpServerTool(Name make_payment), Description(call this function to make payment.)] public static string Make_Payment( [Description(order number), Required] string order_number, [Description(total amount), Required] int total_amount) { if (order_number is null) { throw new McpServerException(Missing required argument order_number); } return Payment proceed successfully. Thank you for your business.; } }Name 属性就是模型看到的工具名Description 是给模型看的说明参数上的 Description 和 Required 决定了模型调用时会不会传对参数。这几个字段写清楚模型调用成功率会高很多。4. 验证请求从 MCP Inspector 到 BotSharp 端到端配置写完不代表能跑得一步步验证。我习惯从底层往上验先验 MCP Server 的工具能不能被发现再验 BotSharp 能不能连上 MCP Server最后验模型能不能通过 TaoToken 调通并触发工具调用。4.1 用 MCP Inspector 验证工具暴露MCP Inspector 是官方提供的调试工具不用安装npx 直接跑npx modelcontextprotocol/inspector跑起来后它会给你一个本地地址浏览器打开填入你 MCP Server 的 SSE 地址比如 http://localhost:58905/sse 。连上后你能看到 Tools 列表里有没有 make_payment、get_pizza_price、place_an_order 这几个工具。如果列表是空的说明 WithToolsFromAssembly 没扫到检查工具类有没有标 McpServerToolType方法有没有标 McpServerTool。在 Inspector 里可以直接调用工具填参数点执行看返回结果。这一步过了说明 MCP Server 本身没问题。4.2 验证 BotSharp 能连上 MCP Server启动 BotSharp 项目看日志里有没有 MCP 客户端连接成功的记录。如果配置里 Enabled 是 trueBotSharp 启动时会去连 McpServerConfigs 里配的地址。连不上会报连接超时或拒绝连接。一个快速的验证方式是看 BotSharp 启动后智能体的可用工具列表里有没有 MCP 工具。你可以在 BotSharp 的前端 UI 里打开 Order 智能体看它的工具配置里是不是出现了 McpTool 类型的条目。如果有说明 MCP 工具已经注册成 BotSharp 的 IFunctionCallback 了。4.3 验证模型通道发一条真实请求最后一步给 Order 智能体发一条消息比如“我想订一个披萨”。如果一切正常你会看到这样的流程模型先调用 get_pizza_types 拿披萨种类回复你选项你选一个后它调用 place_an_order 下单然后问你怎么支付你确认支付它调用 make_payment 完成。这个过程里模型的每一次工具调用决策都是通过 TaoToken 的通道发给模型的。如果模型通道没配好你会看到模型根本没响应或者报 401、404。如果 MCP 没配好模型会回复但不会调用工具因为它看不到工具列表。一个更直接的通道验证方式是单独发一个不涉及工具的请求比如问“你好”看模型能不能正常回复。能回复说明 TaoToken 通道通了剩下的就是 MCP 工具挂载的问题。5. 本篇常见错排查这一节是我实际踩过的坑按报错现象来排查。5.1 401 Unauthorized现象BotSharp 调模型时报 401。原因通常是 ApiKey 填错或者 Key 前面多了空格、少了 sk- 前缀。检查配置里的 ApiKey 字段确保和 TaoToken 控制台里创建的一模一样。另外确认你的 Key 没有过期或被禁用。5.2 404 Not Found现象调模型时报 404。最常见的原因是 Endpoint 填多了路径。TaoToken 的 Base URL 就是 https://taotoken.net/api 不要在后面加 /v1、/chat/completions 或任何其他路径。BotSharp 的 OpenAI 插件会自己拼接完整路径。如果你填了 https://taotoken.net/api/v1 插件再拼一次就变成 /api/v1/v1/chat/completions自然 404。5.3 MCP 工具列表为空现象Inspector 连上了 MCP Server但 Tools 列表是空的。检查三点工具类有没有标 [McpServerToolType]方法有没有标 [McpServerTool]Program.cs 里有没有调 WithToolsFromAssembly。三个都对了还是空确认工具类所在的程序集就是 WithToolsFromAssembly 扫描的那个程序集跨程序集需要额外指定。5.4 BotSharp 连不上 MCP Server现象BotSharp 启动日志报连接 MCP Server 失败。检查 Location 里的地址和端口是否和 MCP Server 实际监听的一致。SSE 地址通常是 http://localhost:端口/sse 端口别写错。另外确认 MCP Server 已经先启动BotSharp 后启动。如果 MCP Server 没起BotSharp 连不上是正常的。5.5 模型不调用工具现象模型能回复但从不调用 MCP 工具。这通常不是通道问题而是工具描述或提示词问题。检查工具的 Description 是否清晰说明了什么时候该调用它。Order 智能体的提示词里要明确写出调用步骤比如“先调用 get_pizza_types 获取选项”。提示词里不写模型可能就自己编答案了。另外确认智能体的工具配置里确实挂上了 McpTool没挂上模型看不到工具。5.6 参数传递错误现象模型调用了工具但参数传错或缺失。检查工具方法参数上的 [Description] 和 [Required] 是否写清楚。参数名要和提示词里提到的一致比如提示词里说 order_number参数名就别写成 orderNumber模型可能会混淆。6. 后续怎么走从 demo 到长期可用的智能体跑通这个 demo 之后你大概已经感受到 BotSharp MCP 的组合威力了。MCP Server 可以独立部署、独立扩展BotSharp 这边只负责调度工具换了、加了改 MCP Server 就行智能体配置基本不用动。如果你打算把这个模式用到长期项目里有几个点值得提前考虑。一是 Key 管理TaoToken 的统一 Key 在多人协作时优势明显不用每个人配一堆供应商的 Key。你可以去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理你的 Key接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 可以查到更细的接口说明。二是如果你要长期跑编码类或 Agent 类任务可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对高频调用场景做了优化比按次调用更适合持续运行的智能体。三是 MCP Server 的部署方式。demo 里用的是本地 SSE生产环境你可能要考虑鉴权、限流、多实例。MCP 协议本身支持多种传输方式SSE 只是其中一种后续可以按需切换。最后说一个实用技巧调试 MCP 工具调用时把 BotSharp 的日志级别调到 Debug能看到模型每次请求的完整 payload 和工具调用结果。这比在黑盒里猜模型为什么没调工具高效得多。我试过在提示词里加一句“如果用户意图涉及下单必须先调用 place_an_order”工具调用成功率明显提升。提示词和工具描述这两块值得你花时间打磨。