复盘:MCP Streamable HTTP 在本服务里怎么跑

复盘:MCP Streamable HTTP 在本服务里怎么跑

这是《本地优先的隐私翻译服务》的第二篇补篇。上一篇拆模型独占锁,这篇拆传输层:一个 POST /mcp 从进 Kestrel 到出结果,中间发生了什么。

之前被网上大量老教程误导,一直以为 MCP = 有状态长连接 + SSE 双端点。实际落地才发现:MCP 传输层已经迭代三代,2026-07-28 版本直接砍掉协议会话、initialize 握手、SSE断线续传,默认走无状态 Streamable HTTP。

一、MCP 传输三代演进

一共5次协议修订,3代传输形态:

  1. 第一代(Legacy,2024-11-05):GET /sse + POST /message 双端点,长连接SSE,现在教程大多停在这版,SDK2.x已经废弃。
  2. 第二代(Legacy,2025-03-26 ~ 2025-11-25):单端点 Streamable HTTP,依赖 Mcp-Session-Id 会话、必须 initialize 握手,有状态。
  3. 第三代(Modern,2026-07-28,当前默认):
    • SEP-2567:移除协议会话、删掉 Mcp-Session-Id
    • SEP-2575:移除 initialize / notifications/initialized 握手,移除 Last-Event-ID 断线续传
    • 不再有全局长连接;subscriptions/listen 替代旧GET端点
    • 每个请求独立携带协议版本、客户端能力,放在 _meta
    • SDK 默认 SessionMode = Stateless

术语区分

  • 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 完整流程

exported_image

抓包核心规则

  1. 同一个POST请求,响应可以是JSON,也可以是 text/event-stream SSE流,由服务端决定
  2. 进度通知 notifications/progress:只有客户端请求带上 _meta.progressToken,服务端才推送进度
  3. 流生命周期 = 当前POST请求,请求断开,流直接结束,不支持续传
  4. 响应头SDK自动添加:
    • X-Accel-Buffering: no:禁止Nginx缓存SSE,否则进度一次性返回
    • Cache-Control: no-cache,no-store:禁止中间层缓存
  5. 错误分层(非常容易搞混)
    • ✅ 工具业务失败:HTTP 200,result.isError: true(模型忙、参数校验失败这类)
    • ✅ JSON-RPC协议错误:返回标准jsonrpc error(方法不存在、反序列化失败)
    • ✅ HTTP 4xx/5xx:传输层错误(406是Accept头不匹配)

示例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 查询

设计思路:无状态不是没有状态,把会话状态变成进程内可查询的资源。任务管理器单例保存任务,任何请求都可以查询任务状态,不绑定客户端连接。

五、踩坑清单

  1. McpException日志级别是fail,带堆栈,但客户端正常收到isError=true
    日志看到 unhandled exception 不用慌,SDK内部捕获,转成业务错误返回,不是服务崩溃。真正故障要关注非OperationCanceledException的handler失败日志。
  2. 客户端取消Token ≠ 推理停止
    只让工具方法返回,底层模型推理还在跑,持续占用显存CPU。
    正确写法:绑定取消令牌,主动终止引擎推理:
using var registration = cancellationToken.Register(() => job.Cancel());

区分:订阅取消=停止接收进度;任务Cancel=停止模型推理,二者不能混。

  1. 两层节流,不要合并
  • 引擎delta事件:120ms,给前端WebUI做打字流式效果
  • MCP进度上报:250ms,给MCP客户端,降低事件频率
  • 段末完成事件强制发送,不受节流控制,防止最后100%进度丢失
  1. 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 开放局域网访问,本服务没有内置认证,内网所有人都能调用模型。

七、总结

  1. 新版MCP Streamable HTTP 往普通HTTP、无状态方向靠拢,适配负载均衡、代理、Serverless;代价是丢掉了会话内主动交互能力。
  2. 流式进度的本质:复用本次POST的SSE响应流,不是独立长连接会话。
  3. 错误分层、注入参数不进schema、Accept头、取消推理,是落地最容易踩的4个坑。
  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

posted @ 2026-11-22 19:28  休休归朴  阅读(7)  评论(0)    收藏  举报