1. 为什么要把现有 WebApi 改造成 Mcp Server你手上大概率已经有一套跑得好好的 ASP.NET Core WebApi接口文档齐全Swagger 一打开就能看到几十个 action。现在想让 AI 工具直接调用这些后端能力比如让 Claude Code 或 Cline 在对话里查一下天气、拉一下订单、触发一次内部任务最直接的想法就是能不能不重写业务逻辑只加一层壳把现有 REST 接口暴露成 MCP 工具答案是可以的。MCPModel Context Protocol本质上是一套标准化的工具描述与调用协议它不关心你后端是 .NET、Java 还是 Go只关心你能不能把「有哪些工具、每个工具要什么参数、调用后返回什么」用标准格式说清楚。ASP.NET Core WebApi 天生带 OpenAPI/Swagger而 OpenAPI 描述和 MCP 工具描述之间几乎是一一对应的这就给了我们一条低成本改造路径。我试过的做法是保留原有 WebApi 项目不动新建一个轻量的 Mcp Server 项目通过读取 WebApi 的 swagger.json把每个 action 自动转换成 MCP Tool再用 TaoToken 统一 Key 打通模型调用链。这样业务代码零改动MCP 层只做协议转换和转发。适合谁适合已经有 REST 接口、想让 AI 工具直接调用后端能力的 .NET 开发者尤其是团队里已经在用 Semantic Kernel 或 Microsoft.Extensions.AI 的同学。整条链路分三段WebApi 暴露 OpenAPI 文档Mcp Server 把 OpenAPI 转成 MCP ToolsMCP Client 把 Tools 喂给模型做 function calling。下面按这个顺序拆开讲每一步都给可复制的代码和配置。2. TaoToken 前置准备统一 Key 与 API 通道在动手写 MCP 之前先把模型调用这一层理顺。很多同学卡在最后一步MCP Server 搭好了Client 也连上了结果模型调用报 401 或者 local proxy failed。根因往往不是 MCP 的问题而是 Key 和 Base URL 没配对。TaoToken 在这里的角色是统一 Key 和 API 通道。你不需要为每个模型厂商单独维护一套 Key也不用在代码里硬编码多个 endpoint。它提供 OpenAI 兼容的接口MCP Client 里用的 ChatClient 只要把 Base URL 指向 TaoToken 的 API 地址Key 换成 TaoToken 的 Key模型 ID 填对应名称即可。具体要准备三样东西第一API Key。到 TaoToken 控制台的 API Keys 页面创建一个复制出来形如sk-xxxx。这个 Key 后面会同时用在 MCP Client 的 ChatClient 配置里。第二Base URL。OpenAI 兼容通道的地址是https://taotoken.net/api注意这里不加任何查询参数直接作为 Endpoint 使用。第三Model ID。根据你要用的模型填比如做中文 function calling 效果比较稳的模型填对应的模型名称字符串即可。三件套凑齐Base URL Key Model ID。如果你还没创建 Key可以先去控制台把 Key 建好顺手在模型对话页面验证一下这个 Key 能不能正常出结果。验证通过再往下走能省掉后面一半的排障时间。这里要提醒一句MCP Server 本身不直接调模型它只负责暴露工具。真正调模型的是 MCP Client。所以 TaoToken 的 Key 是配在 Client 侧的 ChatClient 上不是配在 Server 侧。很多人第一次做会把 Key 塞到 Server 里结果 Client 那边还是连不上模型方向就错了。另外如果你打算长期跑编码类 Agent比如让 Claude Code 通过 MCP 调用你的后端工具建议用 Coding Plan 这类长期方案比按次调用更划算Key 管理也更集中。接入文档里有完整的 Base URL 和参数说明配之前扫一眼能避免拼错地址。3. 可复制配置WebApi 暴露 OpenAPI 与 Mcp Server 项目搭建这一节是全文最核心的部分所有配置片段都可以直接复制。分两步先让 WebApi 吐出标准的 OpenAPI 3.0 文档再新建 Mcp Server 项目读取这份文档。3.1 WebApi 侧确保 swagger.json 可用在你的 ASP.NET Core WebApi 项目里确认已经引入 Swashbuckle 并开启 XML 注释。csproj 里加PackageReference IncludeSwashbuckle.AspNetCore Version8.1.1 /Program.cs 里注册 Swagger 并强制使用 OpenAPI 3.0var builder WebApplication.CreateBuilder(args); builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen(options { options.SwaggerDoc(v1, new OpenApiInfo { Version v1, Title BackendApi }); var xmlFilename ${Assembly.GetExecutingAssembly().GetName().Name}.xml; options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename)); }); builder.Services.AddHttpClient(); var app builder.Build(); app.UseSwagger(options { options.OpenApiVersion Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0; }); app.UseSwaggerUI(options { options.SwaggerEndpoint(/swagger/v1/swagger.json, v1); }); app.UseAuthorization(); app.MapControllers(); app.Run();跑起来后访问http://localhost:5021/swagger/v1/swagger.json能看到完整的 JSON 就说明 WebApi 侧准备好了。这个地址后面要填到 Mcp Server 的配置里。3.2 Mcp Server 侧项目文件与配置新建一个控制台项目csproj 里加三个包ItemGroup PackageReference IncludeMicrosoft.Extensions.Hosting Version8.0.0 / PackageReference IncludeMicrosoft.SemanticKernel.Plugins.OpenApi Version1.47.0 / PackageReference IncludeModelContextProtocol Version0.1.0-preview.11 / /ItemGroup如果你希望把 WebApi 地址、TaoToken 的 Base URL 和 Model ID 做成配置项可以在项目根目录放一个appsettings.json{ WebApi: { SwaggerUrl: http://localhost:5021/swagger/v1/swagger.json }, TaoToken: { BaseUrl: https://taotoken.net/api, ApiKey: sk-你的Key, ModelId: 你的模型ID } }注意 Base URL 写https://taotoken.net/api不要带多余路径。Key 和 Model ID 按你控制台里的实际值填。这个 JSON 片段就是 §3 要求的可复制配置路径和字段名保持原样即可。3.3 把 OpenAPI 转成 MCP Tools 的核心代码Program.cs 里读取 swagger.json 并注册 MCP Serverusing Microsoft.SemanticKernel; using ModelContextProtocol.Server; var kernelBuilder Kernel.CreateBuilder(); Kernel kernel kernelBuilder.Build(); #pragma warning disable SKEXP0040 await kernel.ImportPluginFromOpenApiAsync( pluginName: backend_api, uri: new Uri(http://localhost:5021/swagger/v1/swagger.json), executionParameters: new OpenApiFunctionExecutionParameters { EnablePayloadNamespacing true }); #pragma warning restore SKEXP0040 var builder Host.CreateEmptyApplicationBuilder(settings: null); builder.Services .AddMcpServer() .WithStdioServerTransport() .WithTools(kernel.Plugins); await builder.Build().RunAsync();再补一个扩展方法把 KernelPlugin 里的每个 function 转成 McpServerToolpublic static class McpServerBuilderExtensions { public static IMcpServerBuilder WithTools( this IMcpServerBuilder builder, KernelPluginCollection plugins) { foreach (var plugin in plugins) { foreach (var function in plugin) { builder.Services.AddSingleton( services McpServerTool.Create(function.AsAIFunction())); } } return builder; } }这段代码的关键在ImportPluginFromOpenApiAsync它读取 swagger.json 里每个 action 的元数据构建成 KernelFunction触发时转成 HTTP 调用。AsAIFunction再把 KernelFunction 包装成 AIFunction最终由McpServerTool.Create注册成 MCP 工具。传输层用 stdio适合本机进程间通信如果要远程调用可以换成 SSE 或 streamable。4. 验证请求从工具发现到调用成功配置写完跑一遍完整验证。顺序很重要先起 WebApi再编译 Mcp Server 成 exe最后跑 MCP Client。4.1 启动顺序第一步启动 WebApi 项目确认http://localhost:5021/swagger/v1/swagger.json可访问。第二步编译 Mcp Server 项目产物在bin/Debug/net9.0/McpServerDemo.exe。这个路径要填到 Client 的 StdioClientTransport 里。第三步写 MCP Client。csproj 加ItemGroup PackageReference IncludeMicrosoft.Extensions.AI.OpenAI Version9.4.3-preview.1.25230.7 / PackageReference IncludeModelContextProtocol Version0.1.0-preview.12 / /ItemGroupClient 代码里连接 Mcp Server 并列出工具await using IMcpClient mcpClient await McpClientFactory.CreateAsync( new StdioClientTransport(new() { Name backend_api, Command ..\\..\\..\\..\\McpServerDemo\\bin\\Debug\\net9.0\\McpServerDemo.exe })); var tools await mcpClient.ListToolsAsync(); foreach (AIFunction tool in tools) { Console.WriteLine($Tool Name: {tool.Name}); Console.WriteLine($Tool Description: {tool.Description}); Console.WriteLine(); }4.2 接入 TaoToken 统一 Key把 ChatClient 的 Endpoint 指向 TaoTokenKey 用控制台创建的string apiKey sk-你的Key; var chatClient new ChatClient( 你的模型ID, new ApiKeyCredential(apiKey), new OpenAIClientOptions { Endpoint new Uri(https://taotoken.net/api) }).AsIChatClient(); IChatClient client new ChatClientBuilder(chatClient) .UseFunctionInvocation() .Build(); ChatOptions chatOptions new() { Tools [.. tools] };这里三件套齐了Base URL 是https://taotoken.net/apiKey 是 TaoToken 的 KeyModel ID 填你选的模型。UseFunctionInvocation开启 function calling 支持模型就能自动决定调哪个工具。4.3 一次成功的调用跑起来后控制台会先打印可用工具列表比如GetCurrentDate、GetLocation、GetCurrentWeather。然后进入对话循环输入「今天天气怎么样」模型会先调用GetLocation拿到城市再调用GetCurrentWeather拿天气最后把结果组织成自然语言返回。整个过程你能看到工具名、参数、返回值的流转说明从工具发现到调用成功这条链路是通的。如果工具列表是空的先检查 swagger.json 地址是否可访问如果对话时报 401检查 TaoToken 的 Key 和 Base URL如果报 reading choices 相关错误多半是模型 ID 填错或该模型不支持 function calling。5. 本篇常见错排查排障这块我按真实报错来对照都是踩过的坑。401 Unauthorized。出现在 ChatClient 调用阶段说明 TaoToken 的 Key 无效或没带上。检查ApiKeyCredential里的字符串是不是完整复制前后有没有空格。另外确认 Base URL 是https://taotoken.net/api如果误写成带/v1或其他路径鉴权会失败。local proxy failed。这个报错通常出现在 Client 启动 Mcp Server 进程时Command 路径不对。StdioClientTransport里的 exe 路径是相对 Client 工作目录的建议先用绝对路径验证一次确认能启动再改相对路径。另外确认 Mcp Server 已经编译成功bin 目录下有 exe。reading choices 相关错误。模型返回结构里没有 choices 字段常见原因是 Model ID 填错或者该模型不支持 function calling。换一个明确支持 function calling 的模型 ID 再试。中文场景下选对模型对工具调用成功率影响很大。OAuth 相关报错。如果你用的是 Claude Code 或 Codex 这类工具接入 MCP可能会遇到 OAuth 流程问题。这类工具通常需要你在配置里填 Base URL、Key、Model ID 三件套。以 Codex 的auth.json为例需要确保字段名和层级正确Base URL 指向 TaoTokenKey 填对Model ID 与你要用的模型一致。CC Switch 或 Cline MCP 配置里同理三件套缺一不可。工具列表为空。MCP Client 连上了 Server但ListToolsAsync返回空。检查ImportPluginFromOpenApiAsync的 URI 是否指向有效的 swagger.json以及 WebApi 是否在运行。如果 swagger.json 里 action 没有 XML 注释工具描述会是空的模型可能不愿意调用建议给每个 action 补上 summary。调用工具时报 404。MCP Server 转发 HTTP 请求时Base URL 拼出来的地址不对。检查 WebApi 的实际监听端口和 swagger.json 里的 servers 字段是否一致。如果 WebApi 用了 HTTPS 重定向MCP Server 侧可能拿不到正确地址建议在开发环境用 HTTP。排障的核心思路是分段定位先确认 WebApi 的 swagger.json 可访问再确认 Mcp Server 能列出工具最后确认 ChatClient 能调通模型。哪一段断了就查哪一段不要一上来就怀疑 MCP 协议本身。6. 把工具链接到长期编码流工具链跑通之后真正的价值在于把它接进日常编码流。你可以让 Claude Code 通过 MCP 调用你的后端工具比如查数据库、触发构建、拉取监控指标这些能力一旦标准化成 MCP Tools就能被任何支持 MCP 的 AI 工具复用。如果你打算长期跑这类 Agent 场景建议把模型调用统一走 Coding PlanKey 和额度集中管理不用每次换工具都重新配一遍。接入文档里有完整的 Base URL、Key 获取和参数说明配之前对照一遍能少走弯路。工具发现和调用验证可以在模型对话页面先跑一遍确认模型和 Key 都正常再接到 MCP Client 里。最后留一个实用技巧把 WebApi 的 swagger.json 地址做成环境变量Mcp Server 启动时读取这样本地、测试、生产环境切换时不用改代码。工具描述尽量写清楚参数含义和返回格式模型调用准确率会明显提升。MCP 的重点是标准化一次构建到处使用你的后端能力就这样接进了 AI 工具链。