企业官网建设流程全解析

1. 为什么要在 BotSharp 里接 MCP，以及模型通道怎么选

BotSharp 是一个 .NET 生态里的智能体（Agent）开发框架，它把对话管理、意图识别、函数调用、插件编排这些能力都封装好了，你只要写业务逻辑就能拼出一个能干活儿的智能体。而 MCP（Model 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建完你会拿到一串以 sk- 开头的 Key，复制保存好，后面配置里要用。

API 的基础地址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，直接作为 Base URL 填进去就行。它兼容 OpenAI 的接口格式，所以 BotSharp 里凡是走 OpenAI 协议的地方，把 Base URL 换掉即可。

如果你还没决定用哪个模型，可以先去模型对话页面试一下：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。选一个你熟悉的模型名，比如 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/completions，BotSharp 的插件会自己拼路径。加了反而会 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 填 sse，Location 填你 MCP Server 实际监听的 SSE 地址。端口号要和你 MCP Server 项目启动时一致，不一致就连不上。

3.3 MCP Server 端的工具注册配置

MCP Server 那边，用 MCP C# SDK 注册工具。先装两个 NuGet 包：

<PackageReference Include="ModelContextProtocol" /> <PackageReference Include="ModelContextProtocol.AspNetCore" />

然后在 Program.cs 里启动 MCP Server：

var 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 是 true，BotSharp 启动时会去连 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_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 管理你的 Key，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 可以查到更细的接口说明。

二是如果你要长期跑编码类或 Agent 类任务，可以看看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。它针对高频调用场景做了优化，比按次调用更适合持续运行的智能体。

三是 MCP Server 的部署方式。demo 里用的是本地 SSE，生产环境你可能要考虑鉴权、限流、多实例。MCP 协议本身支持多种传输方式，SSE 只是其中一种，后续可以按需切换。

最后说一个实用技巧：调试 MCP 工具调用时，把 BotSharp 的日志级别调到 Debug，能看到模型每次请求的完整 payload 和工具调用结果。这比在黑盒里猜模型为什么没调工具高效得多。我试过在提示词里加一句“如果用户意图涉及下单，必须先调用 place_an_order”，工具调用成功率明显提升。提示词和工具描述这两块，值得你花时间打磨。