用 .NET 构建 Streamable HTTP 的 MCP 服务器：从 dotnet run 到 MCP Inspector 全流程实战-平芜编程栈

教程
文档
人工智能

【免费下载链接】mcp-for-beginners

This open-source curriculum introduces the fundamentals of Model Context Protocol (MCP) through real-world, cross-language examples in .NET, Java, TypeScript, JavaScript, Rust and Python. Designed for developers, it focuses on practical techniques for building modular, scalable, and secure AI workflows from session setup to service orchestration.

项目地址：https://gitcode.com/GitHub_Trending/mc/mcp-for-beginners

点击查看免费下载

本篇文章围绕本仓库「06-http-streaming」章节中的 .NET 解决方案展开，完整讲解如何基于 Model Context Protocol（MCP）的Streamable HTTP传输方式构建、启动并测试一个 .NET MCP 服务器。你将掌握从dotnet restore恢复依赖、dotnet run启动服务，到使用官方 MCP Inspector 在浏览器与 CLI 两种模式下验证工具（tools）与资源（resources）的完整实战链路，并深入理解Program.cs、Tools.cs等源码背后的实现原理。

一、背景：为什么选择 Streamable HTTP

在 MCP 生态中，传输机制（Transport）决定了客户端与服务器之间数据的交换方式。本仓库 06-http-streaming 章节 README 给出了三种主流传输的对比：

Transport	状态	通知支持	典型用途
stdio	当前	是	本地子进程
HTTP+SSE	已弃用	是	遗留远程实现
Streamable HTTP	当前	是	远程与云端服务器

其中Streamable HTTP是现代的 HTTP 流式传输方式，支持通知机制与更好的可扩展性，被推荐用于大多数生产环境和云场景；而 HTTP+SSE 已在 MCP2025-03-26中被标记为弃用，不建议新实现使用。标准传输是 stdio 与 Streamable HTTP 两种，HTTP+SSE 只出现在旧示例中。

本篇文章聚焦的 .NET 示例正是 Streamable HTTP 的落地实现，其核心价值在于：只需要一个可复制的 .NET 工程，就能演示如何用 ASP.NET Core 承载 MCP 服务器，并通过localhost:3001/mcp端点对外提供工具调用能力。

[!WARNING] 本示例面向 MCP 规范2025-11-25的 Streamable HTTP 实现方式。在 MCP2026-07-28规范中，请求改为自包含的 POST 请求并携带MCP-Protocol-Version、Mcp-Method等头部。在新实现中使用本示例前，请先阅读 MCP 2026-07-28 规范变更说明。

二、.NET 示例工程结构一览

示例位于 03-GettingStarted/06-http-streaming/solution/dotnet/，共包含 6 个文件：

文件	作用
Program.cs	服务器入口，注册 MCP Server 与 HTTP 传输
Tools.cs	定义 MCP 工具（`AddNumbers`）
server.csproj	项目文件，声明`ModelContextProtocol.AspNetCore`依赖
server.sln	解决方案文件
Properties/launchSettings.json	启动配置，定义端口与启动 profile
README.md	示例运行与测试说明（英文原文）

2.1 服务器入口：Program.cs

Program.cs 的核心代码如下：

using server; var builder = WebApplication.CreateBuilder(args); builder.Services .AddMcpServer() .WithHttpTransport(o => o.Stateless = true) .WithTools<Tools>(); builder.Services.AddHttpClient(); var app = builder.Build(); app.MapMcp("/mcp"); app.Run();

关键点逐一解读：

AddMcpServer()：向依赖注入容器注册 MCP 服务器服务；
WithHttpTransport(o => o.Stateless = true)：启用Streamable HTTP传输，并配置为无状态（Stateless）模式。无状态意味着服务器不维护跨请求的会话状态，每次请求自包含，这符合 MCP2026-07-28之后「请求自包含」的趋势，也更适合水平扩展；
WithTools<Tools>()：把Tools类型中的 MCP 工具注册到服务器；
app.MapMcp("/mcp")：把 MCP 端点映射到路由/mcp，即最终的访问地址为http://localhost:3001/mcp。

2.2 工具定义：Tools.cs

Tools.cs 定义了一个最简单的加法工具：

using System.ComponentModel; using ModelContextProtocol.Server; namespace server; [McpServerToolType] public sealed class Tools { [McpServerTool, Description("Add two numbers together.")] public async Task<string> AddNumbers( [Description("The first number")] int a, [Description("The second number")] int b) { return await Task.FromResult((a + b).ToString()); } }

[McpServerToolType]标记该类型为 MCP 工具容器；
[McpServerTool]+[Description]声明工具及其人类可读描述，描述会被自动携带进工具的inputSchema，供 LLM/Agent 理解参数含义；
参数a、b各自带[Description]，这些注解会映射为 JSON Schema 中properties的description字段（后续在 Inspector 输出中可以直接看到）；
方法返回Task<string>，结果是两个整数相加的字符串。

2.3 项目文件：server.csproj

server.csproj 使用Microsoft.NET.Sdk.WebSDK，目标框架为net9.0，并启用了PublishAot（原生 AOT 发布支持）。唯一的关键依赖是官方 MCP 包：

<PackageReference Include="ModelContextProtocol.AspNetCore" Version="0.*-*" />

0.*-*是一个通配版本声明，表示采用可用的最新 0.x 预发布版本，方便跟随 MCP SDK 演进。

2.4 启动配置：launchSettings.json

Properties/launchSettings.json 定义了两种 profile：

http：applicationUrl为http://localhost:3001；
https：applicationUrl为https://localhost:7133;http://localhost:3001。

也就是说，HTTP profile 下服务监听3001 端口，这与测试阶段 MCP Inspector 的访问地址http://localhost:3001完全对应。

三、安装依赖并启动服务器

第 1 步：安装依赖

在示例目录下执行：

dotnet restore

该命令会根据server.csproj中的PackageReference从 NuGet 恢复ModelContextProtocol.AspNetCore等依赖包。

第 2 步：启动示例

dotnet run

启动成功后，服务器会通过 Streamable HTTP 传输监听http://localhost:3001/mcp端点。请保持该终端持续运行，以便下一步进行测试。

四、使用 MCP Inspector 测试（浏览器模式）

在服务器运行于一个终端的同时，打开另一个终端执行：

npx @modelcontextprotocol/inspector http://localhost:3001

该命令会启动一个带可视化界面的 Web 服务器，让你以图形化方式测试示例。

务必确认在 Inspector 界面中将传输类型（Transport）选择为Streamable HTTP，并将 URL 设置为http://localhost:3001/mcp（注意包含/mcp路径）。

服务器连接成功之后，可以进行两类验证：

工具（Tools）：列出工具，然后调用add，传入参数 2 和 4，应当得到结果6；
资源（Resources）与资源模板（Resource Templates）：调用名为greeting的资源模板，输入一个名字，应当返回带有该名字的问候语。

五、CLI 模式测试：更快、更脚本化

浏览器界面适合交互式探索，而在 CLI 模式下运行 Inspector 通常要快得多，也更容易集成到自动化脚本或 CI 流程中。

5.1 列出服务器上所有工具

npx @modelcontextprotocol/inspector --cli http://localhost:3001 --method tools/list

这条命令会列出服务器上所有可用工具，预期输出如下：

{ "tools": [ { "name": "AddNumbers", "description": "Add two numbers together.", "inputSchema": { "type": "object", "properties": { "a": { "description": "The first number", "type": "integer" }, "b": { "description": "The second number", "type": "integer" } }, "title": "AddNumbers", "description": "Add two numbers together.", "required": [ "a", "b" ] } } ] }

可以对照发现：这个 JSON Schema 中的工具名AddNumbers、描述 "Add two numbers together."、参数a/b及各自的描述，正是 Tools.cs 中[McpServerTool]、[Description]注解自动生成的，这直观体现了「属性注解 → 工具 Schema 暴露」的映射链路。

5.2 调用工具

npx @modelcontextprotocol/inspector --cli http://localhost:3001 --method tools/call --tool-name AddNumbers --tool-arg a=1 --tool-arg b=2

预期输出：

{ "content": [ { "type": "text", "text": "3" } ], "isError": false }

isError: false表示调用成功，text: "3"即1 + 2的结果，与 Tools.cs 中(a + b).ToString()的实现完全一致。

5.3 CLI 模式小结

命令片段	含义
`--cli`	以命令行模式运行，不启动浏览器界面
`--method tools/list`	请求`tools/list`方法，列出工具
`--method tools/call`	请求`tools/call`方法，调用工具
`--tool-name AddNumbers`	指定要调用的工具名
`--tool-arg a=1`	为参数`a`传值`1`（可重复使用以传递多个参数）

六、源码级深化：从示例到生产实践的启示

6.1 无状态模式与水平扩展

WithHttpTransport(o => o.Stateless = true)是本示例最具工程价值的配置。在无状态模式下，服务器不需要维护Mcp-Session-Id之类的会话信息，每个 HTTP 请求都独立可处理。这意味着：

服务器可以轻松部署到无状态容器中，配合负载均衡进行水平扩展；
请求失败重试时无需担心会话丢失；
与 MCP 规范向「自包含请求」演进的趋势一致。

从源码结构看，Program.cs 把「MCP 服务注册」「HTTP 传输配置」「工具装配」放在三行链式调用中完成，职责清晰、易于扩展——新增工具只需在Tools类中追加带[McpServerTool]的方法，无需改动启动逻辑。

6.2 工具定义的最佳实践

Tools.cs 展示了 MCP 工具定义的两个最佳实践：

为工具和每个参数提供[Description]：这些描述会进入工具暴露的inputSchema，是 LLM/Agent 正确选择与调用工具的关键元数据；
参数类型尽量明确（int）：明确的类型会让生成出的 JSON Schema 更精确（"type": "integer"且自动加入required），减少客户端传参歧义。

6.3 与同章节其他语言实现的呼应

同一章节还提供了 Python 实现、Java 实现、Rust 实现以及总览性的 solution/README.md。以 Python 为例，其 server.py 与 .NET 版遵循同一套 Streamable HTTP 语义：服务器暴露/mcp端点、提供AddNumbers工具与greeting资源模板，客户端则通过streamablehttp_client建立会话。这种跨语言的同构设计正是本仓库「同一实战、五种语言」课程理念的体现——掌握本篇文章的 .NET 实现后，你可以无障碍地对照阅读其他语言版本。