复盘:MCP Streamable HTTP 在本服务里怎么跑
复盘:MCP Streamable HTTP 在本服务里怎么跑
这是《本地优先的隐私翻译服务》的第二篇补篇。上一篇拆模型独占锁,这篇拆传输层:一个
POST /mcp从进 Kestrel 到出结果,中间发生了什么。
之前被网上大量老教程误导,一直以为 MCP = 有状态长连接 + SSE 双端点。实际落地才发现:MCP 传输层已经迭代三代,2026-07-28 版本直接砍掉协议会话、initialize 握手、SSE断线续传,默认走无状态 Streamable HTTP。
一、MCP 传输三代演进
一共5次协议修订,3代传输形态:
- 第一代(Legacy,2024-11-05):
GET /sse+POST /message双端点,长连接SSE,现在教程大多停在这版,SDK2.x已经废弃。 - 第二代(Legacy,2025-03-26 ~ 2025-11-25):单端点 Streamable HTTP,依赖
Mcp-Session-Id会话、必须 initialize 握手,有状态。 - 第三代(Modern,2026-07-28,当前默认):
- SEP-2567:移除协议会话、删掉
Mcp-Session-Id - SEP-2575:移除 initialize / notifications/initialized 握手,移除 Last-Event-ID 断线续传
- 不再有全局长连接;
subscriptions/listen替代旧GET端点 - 每个请求独立携带协议版本、客户端能力,放在
_meta - SDK 默认
SessionMode = Stateless
- SEP-2567:移除协议会话、删掉
术语区分
- Modern:2026-07-28+,无会话、无握手(本文使用)
- Legacy:2025-11-25及更早,会话+握手
- Dual-era:同时兼容新旧客户端(SDK支持)
核心认知纠正:MCP 现在不是协议层面的长连接有状态服务。流式进度,是复用本次POST请求的响应流,不是独立会话通道。
二、最简注册代码
builder.Services
.AddMcpServer(o =>
{
o.ServerInfo = new Implementation { Name = HyTranslateServices.ServerName, Version = HyTranslateServices.ServerVersion };
o.ServerInstructions = HyTranslateServices.ServerInstructions;
})
.WithHttpTransport() // 显式开启Streamable HTTP,默认也是它
.WithTools<HyTranslateService.Tools.TranslationTools>();
// 路由映射
app.MapMcp("/mcp");
工具类示例:
[McpServerToolType]
public sealed class TranslationTools
{
[McpServerTool(Name = "translate_text", ReadOnly = true, Idempotent = false, OpenWorld = false,
Title = "翻译文本(流式进度 + 可取消)")]
public async Task<string> TranslateText(
[Description("要翻译的原文")] string text,
[Description("目标语言")] string targetLanguage,
IProgress<ProgressNotificationValue> progress, // SDK自动注入,不出现在schema
CancellationToken cancellationToken, // SDK自动注入,不出现在schema
[Description("源语言;留空自动识别")] string? sourceLanguage = null)
{
// 业务逻辑
}
}
关键点:
IProgress<T>、CancellationToken由SDK注入,不会进入工具 inputSchema,AI不会尝试传这两个参数- 参数名自动转为C#驼峰命名;文档、描述里的参数名必须和schema完全一致,否则AI传参报错
三、一次 tools/call 完整流程

抓包核心规则
- 同一个POST请求,响应可以是JSON,也可以是
text/event-streamSSE流,由服务端决定 - 进度通知
notifications/progress:只有客户端请求带上_meta.progressToken,服务端才推送进度 - 流生命周期 = 当前POST请求,请求断开,流直接结束,不支持续传
- 响应头SDK自动添加:
X-Accel-Buffering: no:禁止Nginx缓存SSE,否则进度一次性返回Cache-Control: no-cache,no-store:禁止中间层缓存
- 错误分层(非常容易搞混)
- ✅ 工具业务失败:HTTP 200,
result.isError: true(模型忙、参数校验失败这类) - ✅ JSON-RPC协议错误:返回标准jsonrpc error(方法不存在、反序列化失败)
- ✅ HTTP 4xx/5xx:传输层错误(406是Accept头不匹配)
- ✅ 工具业务失败:HTTP 200,
示例SSE事件片段:
event: message
data: {"method":"notifications/progress","params":{"progressToken":"p1","progress":0,"message":"正在加载模型"},"jsonrpc":"2.0"}
event: message
data: {"method":"notifications/progress","params":{"progressToken":"p1","progress":1,"total":1,"message":"翻译完成"},"jsonrpc":"2.0"}
event: message
data: {"result":{"content":[{"type":"text","text":"你好,世界!"}]},"id":3,"jsonrpc":"2.0"}
四、无状态模式,改变了什么
| 能力 | 表现 | 本项目影响 |
|---|---|---|
| Mcp-Session-Id会话 | 无会话标识 | 无影响 |
| GET /mcp、DELETE /mcp | 不映射,返回405 | 无影响 |
| 旧版SSE双端点 | 禁用,EnableLegacySse和Stateless互斥 | 无影响 |
| SSE断线续传 | Last-Event-ID移除,断了只能重发 | 无影响 |
| 会话内服务端主动询问(elicitation/sampling) | 新版不再支持跨请求主动交互 | 有影响,无法中途弹窗问用户补充术语 |
| 请求结束后推送消息 | 不支持 | 无影响;跨请求状态用独立工具 get_current_translation 查询 |
设计思路:无状态不是没有状态,把会话状态变成进程内可查询的资源。任务管理器单例保存任务,任何请求都可以查询任务状态,不绑定客户端连接。
五、踩坑清单
- McpException日志级别是fail,带堆栈,但客户端正常收到isError=true
日志看到unhandled exception不用慌,SDK内部捕获,转成业务错误返回,不是服务崩溃。真正故障要关注非OperationCanceledException的handler失败日志。 - 客户端取消Token ≠ 推理停止
只让工具方法返回,底层模型推理还在跑,持续占用显存CPU。
正确写法:绑定取消令牌,主动终止引擎推理:
using var registration = cancellationToken.Register(() => job.Cancel());
区分:订阅取消=停止接收进度;任务Cancel=停止模型推理,二者不能混。
- 两层节流,不要合并
- 引擎delta事件:120ms,给前端WebUI做打字流式效果
- MCP进度上报:250ms,给MCP客户端,降低事件频率
- 段末完成事件强制发送,不受节流控制,防止最后100%进度丢失
- Accept头必须同时传两个类型,否则406
Accept: application/json, text/event-stream
只写 application/json,SDK直接返回406空响应。
六、客户端配置(注意type字面量差异)
- Cursor / Claude Desktop
{
"mcpServers": {
"hytranslate": {
"type": "streamableHttp",
"url": "[http://localhost:8086/mcp](http://localhost:8086/mcp)"
}
}
}
- VS Code MCP
{
"mcp": {
"servers": {
"hytranslate": {
"type": "http",
"url": "[http://localhost:8086/mcp](http://localhost:8086/mcp)"
}
}
}
}
坑:Cursor 和 VS Code 的 type 名字不一样,写错不会明确报错,现象就是连不上、初始化失败。
安全提醒:默认监听127.0.0.1;改成
--host 0.0.0.0开放局域网访问,本服务没有内置认证,内网所有人都能调用模型。
七、总结
- 新版MCP Streamable HTTP 往普通HTTP、无状态方向靠拢,适配负载均衡、代理、Serverless;代价是丢掉了会话内主动交互能力。
- 流式进度的本质:复用本次POST的SSE响应流,不是独立长连接会话。
- 错误分层、注入参数不进schema、Accept头、取消推理,是落地最容易踩的4个坑。
- 网上绝大多数教程基于第一代双端点SSE,直接抄会在2.x SDK上失效。
参考:
规范仓库:https://github.com/modelcontextprotocol/modelcontextprotocol/tree/main/docs/specification
Streamable HTTP(draft 对齐2026-07-28):https://modelcontextprotocol.io/specification/draft/basic/transports/streamable-http
SEP-2567(移除会话):https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567
SEP-2575(移除initialize握手):https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575
本文来自博客园,作者:休休归朴,转载请注明原文链接:https://www.cnblogs.com/am1235/p/23746748

浙公网安备 33010602011771号