logo

用 C# 跑通 MCP 工具:从本地调试到安全上线

作者:公子世无双2026.11.17 03:14浏览量:1

简介:面向 .NET 开发者,讲清 MCP C# SDK 的包选择、stdio 与 ASP.NET Core 两种运行方式的完整代码,以及百度智能云接入、模型选型和上线前检查。读完可在本地跑通工具调用,并避免常见的安全疏漏。

一、先确认包与版本

大模型调用外部工具时,过去常要为每个平台单独写插件。MCP(Model Context Protocol)是一个开放协议,规定工具如何描述自己,客户端如何发现和调用工具。支持该协议的客户端可以复用同一套工具,不必为每个平台重写适配代码。

MCP C# SDK 是 .NET 版本的开发包,以 NuGet 包形式发布。它把协议细节封装成 C# 接口,开发者可以沿用依赖注入、ASP.NET Core 等熟悉的方式编写服务器或客户端。具体的维护关系和支持范围,请以项目仓库和 NuGet 页面的说明为准。

SDK 常用的三个包如下。

包名 作用 适合的场景
ModelContextProtocol.Core 协议的基础能力 需要最底层控制时
ModelContextProtocol 构建客户端和服务器的主包 大多数项目的起点
ModelContextProtocol.AspNetCore ASP.NET Core 集成 需要通过 HTTP 对外提供服务时

大多数项目只需要主包。只有需要 HTTP 服务时,才增加 AspNetCore 包。如果只做本地调试,主包已经足够。

版本号不要凭记忆写进文档。开始前,先到 NuGet 页面查看当前稳定版本,并阅读对应的发布说明。本文示例使用的版本如下,发布前请替换为实际查询结果:

  • 稳定版本号:<请填写 NuGet 上的稳定版本号>
  • 查询日期:<请填写 YYYY-MM-DD>

如果稳定版尚未发布,只能使用预览版。此时要在文档里写明预览版号和查询日期,并提醒读者预览版的接口可能变化。

先确认本机环境,再创建项目:

  1. # 查看已安装的 .NET SDK 版本和运行时信息
  2. dotnet --info
  3. # 创建控制台项目
  4. dotnet new console -n McpStdioDemo
  5. cd McpStdioDemo
  6. # 有稳定版时去掉 --prerelease;只有预览版时保留它
  7. dotnet add package ModelContextProtocol --prerelease
  8. dotnet add package Microsoft.Extensions.Hosting
  9. # 确认项目实际引用的版本
  10. dotnet list package

dotnet list package 的输出是判断版本是否正确的依据。编译报错时,先检查 .NET SDK 版本是否满足包的要求,再检查 NuGet 源能否访问。很多报错来自版本不一致,而不是代码本身有问题。

二、stdio 最小服务器

stdio 指标准输入输出。客户端会启动服务器进程,并通过进程的标准输入和标准输出交换协议消息。这种方式不开端口,只在本机进程之间通信,适合本地调试。

这种模式有一个关键约束:标准输出只能用于协议消息。如果日志也写到标准输出,客户端会解析失败,表现为连接断开或工具列表为空。

在项目根目录创建 Program.cs:

  1. using Microsoft.Extensions.DependencyInjection;
  2. using Microsoft.Extensions.Hosting;
  3. using Microsoft.Extensions.Logging;
  4. using ModelContextProtocol;
  5. using ModelContextProtocol.Server;
  6. var builder = Host.CreateApplicationBuilder(args);
  7. // stdio 模式下,标准输出专门用于协议通信,日志必须写到标准错误输出
  8. builder.Logging.ClearProviders();
  9. builder.Logging.AddConsole(options =>
  10. options.LogToStandardErrorThreshold = LogLevel.Trace);
  11. builder.Services
  12. .AddMcpServer()
  13. .WithStdioServerTransport()
  14. .WithToolsFromAssembly();
  15. await builder.Build().RunAsync();

LogToStandardErrorThreshold = LogLevel.Trace 的含义是:级别不低于 Trace 的所有日志都写到标准错误。Trace 是最低的日志级别,因此所有日志都不会进入标准输出。

再创建 EchoTool.cs,定义一个工具:

  1. using System.ComponentModel;
  2. using ModelContextProtocol.Server;
  3. [McpServerToolType]
  4. public static class EchoTool
  5. {
  6. [McpServerTool, Description("原样返回用户输入的文本,用于验证工具调用链路是否通畅。")]
  7. public static string Echo(
  8. [Description("需要返回的文本内容")] string message)
  9. => $"echo: {message}";
  10. }

[McpServerToolType] 标记工具类,[McpServerTool] 标记工具方法。Description 是给模型看的说明。模型依靠这些描述判断何时调用工具、如何填写参数,所以描述要写清楚用途和参数含义。

运行并验证:

  1. # 编译并启动服务器(启动后会等待标准输入,这是正常现象)
  2. dotnet run

直接运行时终端不会输出工具列表,因为服务器在等待客户端发来的协议消息。要验证工具是否可调用,可以使用官方的 MCP Inspector:

  1. npx @modelcontextprotocol/inspector dotnet run --project ./McpStdioDemo

在 Inspector 页面中,连接成功后应能看到 Echo 工具。输入 message 为 hello,返回结果应为 echo: hello。

把服务器接入桌面客户端时,在客户端的 MCP 配置中写入启动命令。路径必须使用绝对路径:

  1. {
  2. "mcpServers": {
  3. "echo-demo": {
  4. "command": "dotnet",
  5. "args": ["run", "--project", "/绝对路径/McpStdioDemo"],
  6. "env": {
  7. "DEMO_API_KEY": "<从密钥管理服务注入,不要写在这里>"
  8. }
  9. }
  10. }
  11. }

常见错误怎么定位

标准输出被污染。 症状是客户端连接后立即失败,或提示解析错误。检查代码中是否有 Console.WriteLine,或日志是否被配置到标准输出。把调试信息改为写入标准错误,或使用日志框架。

SDK 与 .NET 版本不一致。 症状是编译时提示找不到类型或扩展方法。先用 dotnet --list-sdks 查看已安装的 SDK,再对照包的发布说明确认最低要求,必要时升级 SDK 或更换包版本。

NuGet 源不可访问。 症状是 dotnet add package 或还原失败。运行 dotnet nuget list source 查看配置的源,确认网络能访问它。企业网络常需要配置代理或内部镜像。

三、ASP.NET Core HTTP 服务

当工具需要被远程客户端访问时,改用 HTTP 方式。它要求服务有明确的网络地址,因此安全要求比 stdio 高很多。

新建一个 Web 项目,并引用 AspNetCore 包:

  1. dotnet new web -n McpHttpDemo
  2. cd McpHttpDemo
  3. dotnet add package ModelContextProtocol.AspNetCore --prerelease
  4. dotnet list package

同样,稳定版可用后去掉 --prerelease,并以实际查询结果为准。

Program.cs 的内容如下:

  1. using ModelContextProtocol.AspNetCore;
  2. var builder = WebApplication.CreateBuilder(args);
  3. builder.Services
  4. .AddMcpServer()
  5. .WithHttpTransport()
  6. .WithToolsFromAssembly();
  7. var app = builder.Build();
  8. app.MapMcp();
  9. app.Run();

把前面的 EchoTool.cs 复制到本项目,代码不需要修改。

运行并验证:

  1. dotnet run

终端会输出监听地址,例如 http://localhost:5000。MCP 端点的路径以 MapMcp 的默认配置和终端输出为准。打开 MCP Inspector,选择 Streamable HTTP 方式,填入服务地址,即可查看并调用 Echo 工具。

四、接入百度智能云与模型选型

工具服务和模型是两个独立的部分。工具服务负责执行具体操作,模型负责判断何时调用哪个工具、如何填写参数。两者通过 MCP 协议对接,因此工具代码不需要为某个模型重写。

接入百度智能云时,请先查阅其控制台文档,确认所用的模型服务是否支持 MCP,以及以何种方式引入外部工具。不同产品的接入方式可能不同,本文示例不依赖某一平台的专有接口。实际接入前,建议先在本地用 Inspector 验证工具本身,再接入模型平台,这样可以把问题分在两段排查:工具本身有问题,还是模型调用参数有问题。

选择模型时,可以从以下几个维度比较:

  • 工具调用能力:模型能否稳定地按照工具描述生成正确的参数格式。
  • 上下文长度:工具返回的数据量较大时,模型能否完整处理。
  • 响应延迟:多轮工具调用会累加延迟,用户等待时间需要在测试中实际测量。
  • 成本:按调用量计费的模型,要估算每次任务的平均调用次数。

用自己的业务样本做测试,比看宣传数据更可靠。把同一组任务分别交给候选模型,记录工具调用的成功率、参数错误率和平均耗时,再做决定。

五、上线前检查清单

本地跑通不等于可以对外发布。下面的检查项按优先级排列,全部通过后再上线。

安全与访问控制

  • 对外服务必须启用身份验证,不要让任何人都能调用工具。
  • 只通过 HTTPS 对外提供服务,证书由可信机构签发。
  • 检查请求来源,只允许已知的客户端或网段访问。
  • 为接口设置速率限制,防止被滥用导致费用或资源异常。

工具设计

  • 每个工具只做一件事,并遵守最小权限原则。写操作、删除操作与只读查询分开设计。
  • 删除、转账、发送消息等不可逆操作,应要求人工确认,不能完全交给模型自动执行。
  • 对所有输入参数做校验,尤其是文件路径、SQL 片段和 URL。

凭据管理

  • API 密钥、数据库连接串等敏感信息只通过环境变量或密钥管理服务注入。
  • 不要把密钥写进代码、配置文件或日志。
  • 定期轮换密钥,并在泄露时能快速吊销。

日志与监控

  • 记录每次工具调用的名称、耗时和结果状态。
  • 日志中不记录完整的敏感参数

发表评论

活动