用 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>
如果稳定版尚未发布,只能使用预览版。此时要在文档里写明预览版号和查询日期,并提醒读者预览版的接口可能变化。
先确认本机环境,再创建项目:
# 查看已安装的 .NET SDK 版本和运行时信息dotnet --info# 创建控制台项目dotnet new console -n McpStdioDemocd McpStdioDemo# 有稳定版时去掉 --prerelease;只有预览版时保留它dotnet add package ModelContextProtocol --prereleasedotnet add package Microsoft.Extensions.Hosting# 确认项目实际引用的版本dotnet list package
dotnet list package 的输出是判断版本是否正确的依据。编译报错时,先检查 .NET SDK 版本是否满足包的要求,再检查 NuGet 源能否访问。很多报错来自版本不一致,而不是代码本身有问题。
二、stdio 最小服务器
stdio 指标准输入输出。客户端会启动服务器进程,并通过进程的标准输入和标准输出交换协议消息。这种方式不开端口,只在本机进程之间通信,适合本地调试。
这种模式有一个关键约束:标准输出只能用于协议消息。如果日志也写到标准输出,客户端会解析失败,表现为连接断开或工具列表为空。
在项目根目录创建 Program.cs:
using Microsoft.Extensions.DependencyInjection;using Microsoft.Extensions.Hosting;using Microsoft.Extensions.Logging;using ModelContextProtocol;using ModelContextProtocol.Server;var builder = Host.CreateApplicationBuilder(args);// stdio 模式下,标准输出专门用于协议通信,日志必须写到标准错误输出builder.Logging.ClearProviders();builder.Logging.AddConsole(options =>options.LogToStandardErrorThreshold = LogLevel.Trace);builder.Services.AddMcpServer().WithStdioServerTransport().WithToolsFromAssembly();await builder.Build().RunAsync();
LogToStandardErrorThreshold = LogLevel.Trace 的含义是:级别不低于 Trace 的所有日志都写到标准错误。Trace 是最低的日志级别,因此所有日志都不会进入标准输出。
再创建 EchoTool.cs,定义一个工具:
using System.ComponentModel;using ModelContextProtocol.Server;[McpServerToolType]public static class EchoTool{[McpServerTool, Description("原样返回用户输入的文本,用于验证工具调用链路是否通畅。")]public static string Echo([Description("需要返回的文本内容")] string message)=> $"echo: {message}";}
[McpServerToolType] 标记工具类,[McpServerTool] 标记工具方法。Description 是给模型看的说明。模型依靠这些描述判断何时调用工具、如何填写参数,所以描述要写清楚用途和参数含义。
运行并验证:
# 编译并启动服务器(启动后会等待标准输入,这是正常现象)dotnet run
直接运行时终端不会输出工具列表,因为服务器在等待客户端发来的协议消息。要验证工具是否可调用,可以使用官方的 MCP Inspector:
npx @modelcontextprotocol/inspector dotnet run --project ./McpStdioDemo
在 Inspector 页面中,连接成功后应能看到 Echo 工具。输入 message 为 hello,返回结果应为 echo: hello。
把服务器接入桌面客户端时,在客户端的 MCP 配置中写入启动命令。路径必须使用绝对路径:
{"mcpServers": {"echo-demo": {"command": "dotnet","args": ["run", "--project", "/绝对路径/McpStdioDemo"],"env": {"DEMO_API_KEY": "<从密钥管理服务注入,不要写在这里>"}}}}
常见错误怎么定位
标准输出被污染。 症状是客户端连接后立即失败,或提示解析错误。检查代码中是否有 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 包:
dotnet new web -n McpHttpDemocd McpHttpDemodotnet add package ModelContextProtocol.AspNetCore --prereleasedotnet list package
同样,稳定版可用后去掉 --prerelease,并以实际查询结果为准。
Program.cs 的内容如下:
using ModelContextProtocol.AspNetCore;var builder = WebApplication.CreateBuilder(args);builder.Services.AddMcpServer().WithHttpTransport().WithToolsFromAssembly();var app = builder.Build();app.MapMcp();app.Run();
把前面的 EchoTool.cs 复制到本项目,代码不需要修改。
运行并验证:
dotnet run
终端会输出监听地址,例如 http://localhost:5000。MCP 端点的路径以 MapMcp 的默认配置和终端输出为准。打开 MCP Inspector,选择 Streamable HTTP 方式,填入服务地址,即可查看并调用 Echo 工具。
四、接入百度智能云与模型选型
工具服务和模型是两个独立的部分。工具服务负责执行具体操作,模型负责判断何时调用哪个工具、如何填写参数。两者通过 MCP 协议对接,因此工具代码不需要为某个模型重写。
接入百度智能云时,请先查阅其控制台文档,确认所用的模型服务是否支持 MCP,以及以何种方式引入外部工具。不同产品的接入方式可能不同,本文示例不依赖某一平台的专有接口。实际接入前,建议先在本地用 Inspector 验证工具本身,再接入模型平台,这样可以把问题分在两段排查:工具本身有问题,还是模型调用参数有问题。
选择模型时,可以从以下几个维度比较:
- 工具调用能力:模型能否稳定地按照工具描述生成正确的参数格式。
- 上下文长度:工具返回的数据量较大时,模型能否完整处理。
- 响应延迟:多轮工具调用会累加延迟,用户等待时间需要在测试中实际测量。
- 成本:按调用量计费的模型,要估算每次任务的平均调用次数。
用自己的业务样本做测试,比看宣传数据更可靠。把同一组任务分别交给候选模型,记录工具调用的成功率、参数错误率和平均耗时,再做决定。
五、上线前检查清单
本地跑通不等于可以对外发布。下面的检查项按优先级排列,全部通过后再上线。
安全与访问控制
- 对外服务必须启用身份验证,不要让任何人都能调用工具。
- 只通过 HTTPS 对外提供服务,证书由可信机构签发。
- 检查请求来源,只允许已知的客户端或网段访问。
- 为接口设置速率限制,防止被滥用导致费用或资源异常。
工具设计
- 每个工具只做一件事,并遵守最小权限原则。写操作、删除操作与只读查询分开设计。
- 删除、转账、发送消息等不可逆操作,应要求人工确认,不能完全交给模型自动执行。
- 对所有输入参数做校验,尤其是文件路径、SQL 片段和 URL。
- API 密钥、数据库连接串等敏感信息只通过环境变量或密钥管理服务注入。
- 不要把密钥写进代码、配置文件或日志。
- 定期轮换密钥,并在泄露时能快速吊销。
日志与监控
- 记录每次工具调用的名称、耗时和结果状态。
- 日志中不记录完整的敏感参数

登录后可评论,请前往 登录 或 注册