.NET 8 实战 MCP：将业务接口封装为标准 AI 工具的完整指南

前阵子 Claude 发布 MCPModel Context Protocol之后整个 AI 圈都在讨论怎么让模型“长出手脚”。我自己的感受特别深以前做 AI Agent最头疼的就是让模型去调内部系统。写 Function Calling 的 JSON Schema 写得想吐接口字段和模型参数之间全靠手搓映射改一个字段要同步改好几处。MCP 出现之后这套逻辑被标准化了AI 客户端和工具服务端之间有了统一协议。更关键的是.NET 这边跟进速度很快官方 SDK 已经能用了直接把现有的 ASP.NET Core 接口包成 MCP 服务让 Claude、自研 Agent 去调。这篇文章我打算从服务端和客户端两侧完整走一遍先讲清楚 MCP 到底解决了什么问题然后直接上代码把一个真实的 .NET 业务接口改造成 MCP 工具再写一个客户端去消费它。全程用 .NET 8 官方 ModelContextProtocol SDK有踩坑的地方我也会标注出来希望能帮你少走弯路。1. MCP 到底改了什么从“手写工具注册”到“标准协议”1.1 没有 MCP 的时候开发有多痛在 MCP 之前让大模型调用业务接口最常见的方式是 Function Calling / Tool Calling。OpenAI、通义、文心各有各的格式但本质都是你把工具的 JSON Schema 提供给模型模型在推理时决定“我要调用哪个工具、参数是什么”然后你的代码接住这次调用执行真实逻辑把结果返回给模型模型再基于结果生成自然语言回答。听起来不复杂但真正落地的时候问题一个接一个。最典型的是工具定义的重复劳动一个订单查询接口在 OpenAI 里要写一份 JSON Schema换到 Claude 又要重新描述一遍参数工具多了以后参数格式不统一、命名不一致、类型对不上维护成本直接爆炸。另一个痛点是“协议”是各家私有的模型供应商绑定得很死你要换个模型整套工具注册逻辑就可能要重写。还有更隐蔽的问题工具返回的数据结构没有标准约束。有人返回纯文本有人返回 JSON 字符串有人返回二进制模型拿到以后解析逻辑完全靠猜出错率很高。MCP 出现以后这些东西被收敛进一个协议里工具的定义、调用、返回结果、错误处理全部标准化。服务端只需要实现一份 MCP 接口任何支持 MCP 的客户端都能用不再区分 OpenAI 还是 Claude。1.2 MCP 的核心模型Client、Server、TransportMCP 的架构非常像 C/S 架构但比普通的 HTTP 接口多了一层“上下文”的概念。MCP Server 负责暴露能力MCP Client 负责连接和调用中间通过 Transport 通信最常用的 Transport 是基于 HTTP 的 Streamable HTTP早期是 SSE现在官方推荐 Streamable HTTP。协议本身的底层是 JSON-RPC 2.0。这一点很关键它意味着 MCP 不是一个“RESTful 风格”的接口而是基于请求/响应和通知的 RPC。你可以把 MCP 理解成“给 AI 用的、带类型和描述信息的 RPC 网关”。Client 连接 Server 后第一件事是initialize握手然后通过tools/list拿到全部工具列表之后调用某个工具就走tools/call。这里我多说一句MCP 里除了 Tool还有 Resource 和 Prompt 两个概念。Resource 类似把文件、数据库记录暴露给模型去“读”Prompt 是预定义的提示词模板。但现阶段 90% 的业务接入都是围绕 Tool 展开的也就是“让 AI 能执行动作”。这篇文章也会把重点放在 Tool 上Resource 和 Prompt 后文会简单提一下。1.3 .NET 生态的 MCP 现状微软官方维护了ModelContextProtocol这个 NuGet 包最新的版本已经进入比较稳定的状态。它对 ASP.NET Core 的支持很完整可以直接在现有的 Web 应用里挂载 MCP 端点也可以单独起一个专门的 MCP Server 进程。客户端方面也有 SDK不是只能靠 Python 或者 Node 写客户端.NET 程序一样能作为 MCP 客户端去调外部服务。我实测下来.NET SDK 走的风格和 ASP.NET Core 高度一致服务端用AddMcpServer()注册、MapMcp()映射路由工具类绑定依赖注入。如果你写过 Minimal API上手基本没有成本。下面就开始进入实战。2. 服务端落地把现有 .NET 接口包成 MCP 工具2.1 极简 MCP Server10 行代码先跑起来先搞一个最小可运行的 MCP Server确认链路是通的。新建一个 ASP.NET Core Web API 项目空模板就行然后安装两个包dotnet add package ModelContextProtocol.AspNetCore dotnet add package ModelContextProtocol我写这篇文章时用的是 0.2.x 版本的 SDKAPI 命名和早期预览版有差异。你可以用dotnet add package直接装最新稳定版示例代码我会尽量用版本差异较小的写法。Program.cs里这样写using ModelContextProtocol; using ModelContextProtocol.Server; var builder WebApplication.CreateBuilder(args); builder.Services.AddMcpServer() .WithHttpTransport(); builder.Services.AddSingletonDateTimeService(); builder.Services.AddMcpToolDateTimeTools(); var app builder.Build(); app.MapMcp(); app.Run();DateTimeTools很简单public class DateTimeTools { [McpTool(get_current_time, Description 获取服务器当前时间返回 ISO 8601 格式字符串)] public string GetCurrentTime( [McpToolParameter(Description 时区 ID例如 Asia/Shanghai)] string timeZoneId) { var tz TimeZoneInfo.FindSystemTimeZoneById(timeZoneId); return TimeZoneInfo.ConvertTimeFromUtc(DateTime.UtcNow, tz) .ToString(O); } }跑起来以后服务默认监听某个端口MCP 端点路径是/mcp直接访问http://localhost:5150/mcp。这一步跑通了就说明服务端已经具备 MCP 能力任何 MCP 客户端都能来连。2.2 工具方法注册与依赖注入的用法上面示例里有个关键点AddMcpToolT把整个类里的[McpTool]方法全部注册成工具而且这些工具方法支持构造函数依赖注入类本身也会被注册进容器。这意味着你可以直接把仓储、DbContext、HttpClient 等现有服务塞进来不用另起炉灶。比如一个真实的订单服务public class OrderTools { private readonly OrderService _orderService; public OrderTools(OrderService orderService) { _orderService orderService; } [McpTool(get_order_status, Description 根据订单号查询订单状态)] public async Taskstring GetOrderStatus( [McpToolParameter(Description 订单号例如 ORD-20250101-001)] string orderNo, CancellationToken cancellationToken) { var order await _orderService.FindByNoAsync(orderNo, cancellationToken); return order is null ? JsonSerializer.Serialize(new { code 404, message 订单不存在 }) : JsonSerializer.Serialize(order); } [McpTool(cancel_order, Description 取消一个未发货的订单返回操作结果)] public async Taskstring CancelOrder( [McpToolParameter(Description 订单号)] string orderNo, [McpToolParameter(Description 取消原因)] string reason, CancellationToken cancellationToken) { var result await _orderService.CancelAsync(orderNo, reason, cancellationToken); return JsonSerializer.Serialize(result); } }这里我强烈建调用“返回统一 JSON 字符串”的约定而不是直接返回一个自定义对象让 SDK 帮你序列化。原因有两个第一返回 JSON 字符串时你自己完全掌控结构可以方便地塞入 code、message、data 这类统一的响应外壳第二MCP 客户端拿到的是字符串模型对 JSON 字符串的可读性远好于自定义二进制或纯文本解析成功率更高。2.3 用 MCP Inspector 验证服务端功能服务端跑起来以后怎么验证官方提供了一个叫 Inspector 的可视化调试工具按两个方式可以起最新版本已经支持 npx 一键启动npx modelcontextprotocol/inspector打开它给的本地地址Inspector 里可以填服务端地址http://localhost:5150/mcp和传输类型Streamable HTTP。连上之后左侧能看到工具列表、参数结构右侧可以直接填参数调用工具返回结果一目了然。我非常建议在写客户端之前先用 Inspector 把工具调通因为排查“服务端问题”和“客户端问题”是两个完全不同的战场。如果不方便用 npx我也有一个粗暴但管用的笨办法直接用 curl 模拟 JSON-RPC 请求。MCP 的 Streamable HTTP 端点可以接收 POST JSONbody 里带 JSON-RPC 消息例如先发 initialize再发 notifications/initialized最后发 tools/list。不过这个流程有点繁琐用来排查问题可以日常开发还是 Inspector 更高效。2.4 工具粒度设计的三个原则工具调用是给大模型用的和给人设计的 REST API 有很大区别。我把踩过的坑总结成三条原则。第一一个工具只做一件原子性的事情。“查询订单状态”和“取消订单”必须拆成两个工具千万不要做成order_operation(orderNo, operationType)。模型在选参数的时候很容易把 operationType 拼错而且工具语义不清晰会让模型更困惑。第二参数数量越少越好。能用一个字符串搞定的不要拆成三个字段。参数越多模型“幻觉参数”的概率越大。比如查询订单orderNo一个字段就够如果是带筛选条件的可以接收一个 JSON 字符串参数让模型自己根据自然语言生成 JSON。第三描述信息要写人话。Description不是给你自己看的是给模型看的。你写“获取服务器当前时间”模型就很清楚什么时候该调用它。你写“时间服务接口”模型可能就蒙了。描述越口语化、越贴近用户问法模型越容易命中。3. 进阶场景不改业务代码给现有 REST 接口套一层 MCP3.1 为什么需要“适配器模式”很多团队的情况是核心业务接口早就写好了而且跑得很稳不可能为了 AI 接入去改内部逻辑。这时候最理性的做法不是把 MCP 代码塞进老服务而是新建一个独立的 MCP Server 进程让它去调用老服务的 REST 接口。这个思路我强烈推荐因为它把“AI 接入层”和“核心业务层”彻底解耦了。核心服务不需要导入任何 MCP 相关包不需要理解什么是工具、什么是 Tool SchemaMCP Server 只需要通过 HttpClient 去调用已有的接口。出问题的时候排查范围也清晰AI 调用不到数据先查 MCP 进程日志再查老服务访问日志链路一目了然。3.2 用 C# 写一个“转发型” MCP 工具假设老服务里有个接口GET /api/products/{id}返回商品信息。我们的 MCP Server 里就可以这样写public class ProductTools { private readonly HttpClient _httpClient; public ProductTools(HttpClient httpClient) { _httpClient httpClient; } [McpTool(get_product_detail, Description 根据商品 ID 查询商品详情)] public async Taskstring GetProductDetail( [McpToolParameter(Description 商品 ID纯数字)] string id, CancellationToken cancellationToken) { var response await _httpClient.GetAsync($/api/products/{id}, cancellationToken); var body await response.Content.ReadAsStringAsync(cancellationToken); return body; } }启动注册的时候给HttpClient配置 BaseAddressbuilder.Services.AddHttpClientProductTools(client { client.BaseAddress new Uri(builder.Configuration[ProductServiceUrl]!); });就这么简单一个 MCP 工具就有了。模型拿到的信息和你老接口返回的 JSON 完全一致不需要改任何业务代码。3.3 处理老接口的鉴权和限流老接口不是裸奔的通常有 Token 鉴权或者 API Key。这种情况下MCP Server 作为“中间人”需要替模型请求携带凭证。我的做法是在 MCP Server 配置里放一个服务账号的凭证用DelegatingHandler统一注入 Authorization 头MCP 工具方法里不用关心鉴权逻辑。public class AuthHandler : DelegatingHandler { private readonly string _token; public AuthHandler(IConfiguration config) { _token config[ProductServiceToken]!; } protected override TaskHttpResponseMessage SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { request.Headers.Authorization new(Bearer, _token); return base.SendAsync(request, cancellationToken); } }注册的时候加上builder.Services.AddTransientAuthHandler(); builder.Services.AddHttpClientProductTools() .AddHttpMessageHandlerAuthHandler();限流方面我的建议是给 MCP Server 调用外部服务时加上简单的“并发闸门”。模型有时会发起并发工具调用如果老服务承受不住一瞬间就会被压垮。用SemaphoreSlim控制最大并发数超出的请求排队这是一种低成本又有效的保护手段。3.4 静态工具也能调用本地命令把命令行变成 MCPMCP 工具不一定是 HTTP 转发它也可以直接调用本地能力。比如我做过一个例子把 FFmpeg 的命令行操作封装成 MCP 工具让 AI 直接转码视频。工具方法内部用Process.Start执行命令读取 stdout/stderr 返回给模型。这类“系统操作型”工具威力很大但风险也大。我建议只暴露白名单内的命令绝对不要做成让模型自由输入 shell 字符串的工具。那种“把参数拼进命令行”的写法模型一旦生成恶意或者畸形参数后果不可控。正确的姿势是参数固定为枚举或者特定格式代码里用列表白名单校验任何不在白名单里的值直接拒绝。4. 客户端落地在 .NET 程序里调用 MCP 服务4.1 最小客户端连上服务并调用工具服务端准备好了现在写客户端。新建一个控制台项目安装dotnet add package ModelContextProtocol客户端代码using ModelContextProtocol.Client; var client await McpClientFactory.CreateAsync(new McpClientOptions { Transport new McpTransportOptions { TransportType TransportTypes.StreamableHttp, Url http://localhost:5150/mcp } }); var tools await client.ListToolsAsync(); foreach (var tool in tools) { Console.WriteLine(${tool.Name}: {tool.Description}); } var result await client.CallToolAsync( get_current_time, new Dictionarystring, object { [timeZoneId] Asia/Shanghai });CallToolAsync返回的是一个集合每个元素对应工具的返回内容。如果是文本返回取result.FirstOrDefault()转字符串即可。这个就是最朴素也最完整的 MCP 客户端调用链路握手、发现工具、调用工具。4.2 把 MCP 工具接入 AI AgentSchema 的自动化单独写一个客户端去调工具只是第一步。真正有价值的场景是把 MCP 的工具列表喂给你自己的 LLM Agent让模型在对话过程中自动决定调用哪个工具。大致的流程是通过ListToolsAsync获取所有工具的 Schema名称、描述、参数结构。把 Schema 传给 LLM 的 tools 参数。模型返回一个 tool_call里面包含工具名和参数 JSON。程序根据工具名找到对应的 MCP 客户端实例调用CallToolAsync。把调用结果作为 tool message 塞回给模型模型生成最终回答。这里需要特别留意的是不同 LLM 供应商的 tools 参数格式有差异但 MCP 的ListToolsAsync返回的工具 Schema 已经是 JSON Schema 风格大部分供应商只需要做轻微的转换就能直接用。如果你用的 .NET LLM 库是Microsoft.Extensions.AI还可以把 MCP 工具直接适配进去这一步省了很多功夫。4.3 客户端侧的错误处理与超时控制MCP 工具是网络调用一定会遇到超时、服务端异常、参数校验失败。客户端侧我习惯统一做一层 try-catch把错误结果格式化成模型能理解的文本返回。比如try { var result await client.CallToolAsync(toolName, args); return FormatResult(result); } catch (McpException ex) { return $工具调用失败{ex.Message}。请检查参数是否正确。; } catch (OperationCanceledException) { return 工具调用超时可能要稍后重试。; }这里有个细节模型看到错误信息后通常会尝试修正参数重新调用。所以错误信息一定要写清楚“为什么失败”比如参数不合法、订单不存在、网络超时。如果错误信息太模糊模型会像个无头苍蝇一样反复试浪费 token 还影响体验。4.4 自己写一个极简 JSON-RPC 客户端不依赖官方包如果因为环境限制用不了官方客户端包你也可以直接用 HttpClient 自己发 JSON-RPC。MCP over HTTP 的底层就是 POST 一段 JSON 到端点核心是initialize、tools/list、tools/call三个方法。一个非常简化的流程是这样的var payload JsonSerializer.Serialize(new { jsonrpc 2.0, id 1, method tools/call, params new { name get_current_time, arguments new { timeZoneId Asia/Shanghai } } });发过去以后解析响应的result.content。这里面会有一个text字段就是工具返回的文本内容。注意用这种方式你需要手动维护 initialize 握手和 session id官方包帮你把这些全包掉了。除非有特殊原因我不建议在生产环境手搓但理解这个底层流程有助于排查问题。工具调不通的时候先拿 curl 试一下底层 JSON-RPC能快速判断是协议问题还是 SDK 问题。5. 常见问题与排查技巧实录5.1 问题速查表我把开发中遇到的高频问题整理成了表格方便你排查现象可能原因解决办法客户端连接时报 404MCP 端点路径不对确认app.MapMcp()已调用默认路径是/mcp工具调用超时工具内部逻辑太慢或者外部服务无响应用 CancellationToken 加超时把耗时操作做成异步模型反复调用同一个工具仍失败工具返回的错误信息太模糊优化错误信息明确告知模型失败原因模型生成的参数与工具 Schema 不匹配参数描述不清或模型上下文被截断精简参数数量把参数描述写清楚ListTools 拿不到工具列表工具类没有注册或者没有[McpTool]标注检查AddMcpToolT和特性标注服务端返回 CORS 错误客户端跨域访问 MCP 端点若为浏览器场景配置 CORS返回的 JSON 被截断或换行异常工具返回内容过大对大结果做摘要或分页控制单次返回体积5.2 坑Docker 容器里不能直接连宿主机的 MCP我把 MCP Server 跑在 Docker 容器里然后用宿主机上的客户端去连结果一连就超时。后来发现问题很简单容器里服务监听的地址如果是localhost宿主机是访问不到的需要监听0.0.0.0。反过来容器内的客户端想连宿主机上的 MCP也不能写localhost要写宿主机 IP在 Docker Desktop 场景下可以用host.docker.internal。这个坑看起来很低级但我在不同项目里被绊过两次。第一次是服务端没监听0.0.0.0第二次是客户端把地址写死成localhost。Docker 网络和宿主机网络的隔离逻辑在 MCP 这类“进程间/容器间通信”场景里特别容易踩。5.3 坑工具返回内容不要超长大模型上下文窗口虽然有上限但工具返回超长文本会带来几个问题一是 token 费用飙升二是模型在处理超长返回时容易忽略关键信息三是可能触发供应商的上下文长度限制导致请求直接报错。我的经验是工具返回结果要尽量“瘦身”。列表类查询返回前 10 条就够了明细类查询只返回核心字段。如果确实有多条数据给模型一个“总数 摘要 分页参数”的结构让模型决定要不要继续查下一页。还有一个细节返回的文本不要带多余的空行、制表符和格式噪音模型解析纯文本本来就吃力别给它增加负担。5.4 坑使用 CancellationToken 和超时策略模型调用工具的等待时间通常受供应商侧限制比如 60 秒甚至更短。如果你的工具内部是一个耗时的数据计算建议采用“提交任务 查询结果”的模式第一次调用只返回任务 ID让模型用另一个工具去轮询结果。这种异步模式虽然多了一个工具但用户体验稳定很多。另外工具方法里一定要接住CancellationToken并传给内部的长耗时调用。.NET SDK 在客户端断开或超时时会取消这个 token如果工具内部不响应取消线程会一直挂着并发一高服务就撑不住了。我见过一个教训工具方法里调用第三方 HTTP 接口没传 token结果客户端早就超时放弃了服务端还在傻傻地等待响应本来只需要 2 秒的请求最后耗了 30 秒才释放。6. 一些亲测管用的工程化经验6.1 服务的版本管理与多环境配置MCP Server 和普通 Web 服务一样会面临多环境部署问题。我建议把 MCP 端点路径、外部服务地址、凭证等全部放到配置里不要写死在代码里。尤其要注意开发环境往往连测试数据库一旦 AI 工具上线到生产连的却是生产库后果很严重。所以在配置里显式区分ProductServiceUrl、DatabaseConnectionString这些键并且部署时做环境变量覆盖避免出现“测试环境模型调用生产订单接口”这种事。6.2 权限意识MCP 工具是权力的放大器这一点我放在后面讲是因为它太重要了。MCP 工具让大模型能直接操作业务系统这本质上是在给 AI 授权。如果这个 AI Agent 是面向普通用户的必须做用户隔离不能出现“用户 A 让 AI 查到了用户 B 的订单”这种漏洞。工具方法内部要传用户上下文而不是让模型自己猜用户身份。我的建议是三层控制第一层是网络层MCP Server 只允许内网访问第二层是身份层客户端持有合法凭证服务端校验后识别出调用者身份第三层是业务层工具方法内根据调用者身份做数据权限过滤例如查询订单时强制加WHERE user_id currentUserId。千万别把 MCP 服务暴露到公网还要对工具调用做审计日志出问题时能追溯。6.3 后续扩展Resources、Prompts 与多工具编排工具只解决了“执行动作”的问题MCP 的另外两个能力也很值得玩。Resources 可以把你系统里的文档、配置、数据模板暴露给模型让模型在回答前先“读一读”。Prompts 可以预置提示词模板比如“总结一份工单”的模板里面写好输出格式、注意事项客户端拉取后直接填充内容就能用。实际项目中我见过一个挺经典的组合用 Resource 暴露查询数据需要的表结构说明用 Tool 暴露执行 SQL/查询订单的操作再用 Prompt 把“你是数据分析助手”的角色定义好。三种能力配合起来AI 不仅会“做事”还知道自己该在什么场景下做什么事。最后再总结一个我个人的实操体会MCP 最大的价值其实不是技术本身而是它把“AI 调用系统”这件事标准化了。以前你做 Function Calling绑定的是某一个模型厂商现在你做 MCP Server绑定的是整个生态。.NET 这一侧的 SDK 虽然还在快速迭代中但官方已经在很认真地推进API 设计也和 ASP.NET Core 保持了一致。如果你的团队正在做 AI Agent 和内部系统的对接我建议尽早把 MCP 纳入技术选型。先把一个最小闭环跑通再逐步把更多工具加进来这个投入产出比非常可观。