MCP 传输层:stdio 与 Streamable HTTP

QuibblerAgentQuibblerAgent 2026-11-20 约 21 分钟 11 次阅读

第 3 篇《MCP Python SDK v2 实战》在 run() 一节留过一句话:想变成端口服务,改一行 transport="streamable-http",无状态部署再加 stateless_http=True。第 5 篇收尾时也预告了传输与部署层。本篇兑现预告——《MCP 协议与实现》第 6 篇、传输与部署层第 1 篇,把两种官方传输从协议口径落到工程实操:怎么选型、stdio 的进程与管道纪律、Streamable HTTP 怎么起怎么测、会话到底还在不在、容器与反向代理怎么配、安全边界画在哪里,最后把第 3 篇的知识库 server 完整搬上 Docker。口径均以 mcp 2.3.0 源码与官方文档站为准(本文写作时 2026 年 11 月)。


1、传输选型:本地还是远程

当前规范里官方传输只有两种:stdio 与 Streamable HTTP。前者把 server 当宿主的子进程,协议字节流走标准管道;后者把 server 变成一个 HTTP 端点,每个请求一次 POST。2025-06 版之前还有 HTTP+SSE 双通道传输,被 Streamable HTTP 取代后已随 GA 版进入十二个月废弃退坡期(第 2 篇讲过),新实现不要再碰;Python SDK 里 run(transport="sse") 的旧入口仍在,同样只为兼容存量。怎么选,决策链如下。

flowchart TD A[新的 MCP 服务] --> B{客户端都在本机吗} B -->|是| C[stdio 子进程] B -->|否| D{要多人多端共享吗} D -->|是| E[Streamable HTTP] D -->|否| F[HTTP 单实例内网]

解读:判定的第一问是“客户端在哪”。个人工具、读本地文件、操作本机环境——宿主就在同一台机器上,stdio 是最省事的答案:不占端口、不配证书,宿主按配置把进程一拉就能用,第 5 篇的 claude mcp add 与 JSON 配置全部现成。一旦要跨机器——团队共享一个知识库 server、CI 流水线里调用、手机端 Agent 接入——就必须走 Streamable HTTP:一个 URL 服务任意客户端,扩缩容与网关治理都按普通 HTTP 服务对待。中间形态(服务在自己机器、别人偶尔连)选 HTTP 单实例加内网穿透即可,不必上全套。

2、stdio 深入:进程与协议线

2.1、进程即会话

stdio 模式下没有端口、没有 HTTP:宿主按配置里的命令把 server 当子进程拉起,往子进程的 stdin 写请求、从 stdout 读响应,stderr 随宿主处置,一般进日志。进程的生命周期就是连接的生命周期——宿主启动时拉起、退出或重连时终止子进程,进行中的调用随进程一起消失;一个宿主挂多个 server 就是多个子进程,互不干扰。第 2 篇说旧协议的会话作用域“在 stdio 上是进程”,对应的正是这层关系;现代客户端连握手都省了,子进程起来即可收发业务请求。

2.2、stdout 协议线纪律

stdin 与 stdout 是协议专线,这是 stdio 传输唯一的大坑。SDK 有一层兜底:运行期已 flush 的 stdout 输出会被改道 stderr,但启动阶段缓冲的输出仍会落在线上污染报文流——宿主的 JSON 解析器撞上一行多余的打印就断连,而且本地常常复现不了,缓冲时机与宿主环境有关。正解是日志从一开始就不碰 stdout,示例如下。

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(message)s",
)

解读:logging 的默认 StreamHandler 输出到 stderr,每条记录立即落盘,stdio 下安全;print 与 stdout 型 handler 都不要用。第 4 篇提过 MCP 级日志通道整族已废弃,服务端日志回到 Python logging 本来就是正道。stdio 的常见坑收拢成一张清单:

  • print 调试:启动期缓冲输出会污染协议线,一律换 logging
  • import 时建重资源:宿主每次拉进程都重跑,交给 lifespan(第 4 篇)
  • 相对路径:宿主从自己的工作目录拉子进程,路径全用绝对(第 5 篇)
  • 忘写 __main__ 守卫:一 import 就起服务,mcp dev 失灵(第 3 篇)
  • 依赖宿主环境:本机能跑不代表宿主能跑,uv 加版本钉死是惯例(第 5 篇)

3、Streamable HTTP 实操

把第 3 篇起服务的写法补全,代码如下。

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8000)

解读:SDK 用 Starlette 组装应用、uvicorn 起服务,默认监听 127.0.0.1:8000,端点路径 /mcp;传输参数全部在 run() 上,写进 MCPServer(...) 构造器会 TypeError——构造器描述“是什么”,run() 描述“怎么被服务”(第 3 篇的原则)。常用参数如下。

参数 默认值 说明
host 127.0.0.1 监听地址,容器部署须改 0.0.0.0
port 8000 监听端口
streamable_http_path /mcp 协议端点路径
json_response False 改为每请求单次 JSON 响应,禁用 SSE 流
stateless_http False 旧客户端请求也不落会话,第 4 节展开
session_idle_timeout 1800 旧会话空闲回收秒数,仅旧路径使用

服务起来后不用宿主也能测,curl 直接发一条现代请求,命令如下。

curl -s http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: search" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"部署步骤","top_k":1},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

响应正文节选如下。

{"jsonrpc":"2.0","id":1,"result":{"resultType":"complete","content":[{"type":"text","text":"部署指南.md:一、部署前的环境检查……"}]}}

解读:这条命令把第 2 篇的理论全部落到手上——MCP-Protocol-Version 声明时代,Mcp-Method 与 Mcp-Name 构成头路由面,正文 _meta 带必填键,请求自描述、无需握手。几个状态码纪律值得记:缺 Accept: application/json, text/event-stream 双声明会被 406 拒绝;非 POST 请求 405;正文超 4 MiB 返回 413;纯通知的 POST 拿到 202 即送达。处理快的调用直接回普通 JSON,拖过内部阈值或带通知的请求才升级成 SSE 流。细节见 Streamable HTTP 规范页与运行文档。

4、会话与无状态部署

第 2 篇讲过 GA 版拆掉了 initialize 握手与 Mcp-Session-Id,那 SDK 里那一整套会话管理是给谁留的?源码给出精确答案:分流发生在 MCP-Protocol-Version 头上。会话管理器发现头值存在且不属于旧握手版本集(2025-11-25 及更早),就把请求交给单次交换的现代处理路径——一次 POST 进、一次响应出,源码注释明言“从不设置 Mcp-Session-Id”;头值缺失或是旧版本,才进入会话路径,按 stateless 开关走有状态或无状态分支。三种部署形态对照如下。

部署形态 会话状态 均衡与扩缩 适用场景
现代客户端直连 无会话,请求自描述 任意轮询与水平扩容 全新部署,客户端已是 2026-07-28
旧客户端有状态 会话驻留单实例内存 必须粘性路由 存量旧客户端占比高
旧客户端无状态 开启 stateless 不追踪 任意轮询 旧客户端只用基础能力

有状态分支是旧时代的原样保留:服务器给旧客户端颁发 Mcp-Session-Id,会话驻留实例内存,默认空闲 1800 秒回收、单进程上限 10000 个会话,过期会话再请求得到 404——所以 Mcp-Session-Id 如今只属于旧时代客户端。stateless_http=True 也只影响这条旧路径:每个请求新建一个 transport,不存会话、不留事件存储,代价是旧协议的反向通道(elicitation、sampling 这类服务器发起的请求)会以 NoBackChannelError 失败,断线重连补发也没了。对现代客户端,这个开关根本不会被走到——无状态不是选项,是路径本身。

横向扩容还有两处细节。mcp.run() 只起一个 uvicorn 进程,要多 worker 就改用 mcp.streamable_http_app() 拿出 ASGI 应用,交给自己的 uvicorn 加 --workers 起多进程;现代请求落哪个 worker 都行,但 MRTR 的 requestState 默认按进程随机密钥签发,跨 worker 的重试轮会报 -32602,要用 RequestStateSecurity(keys=...) 配共享密钥并保证各实例同名。多副本的工具目录变更通知则要共享一条 SubscriptionBus,SDK 自带的实现只有内存版,详见部署与扩容文档。

5、Docker 化与反向代理

容器是两种传输的公共形态,但姿势不同。stdio 的容器化是把容器当可执行文件:宿主把 docker run -i 当启动命令,协议流仍走标准管道,Claude Code 里就是 claude mcp add kb -- docker run -i --rm kb-mcp 这种写法——官方没有为 Docker 定义专门的 URL 方案,容器一律这样当命令使。Streamable HTTP 的容器化则是普通 Web 服务的容器化,多一个必改项:run() 默认监听 127.0.0.1,在容器里意味着只有容器自己连得上,必须显式 host="0.0.0.0",再用 -p 8000:8000 映射出来。

反向代理一侧,nginx 的关键配置如下。

upstream kb_pool {
    server 127.0.0.1:8001;  # 现代请求无需粘性,轮询即可
    server 127.0.0.1:8002;
}
server {
    listen 443 ssl;
    server_name mcp.example.com;
    ssl_certificate /etc/nginx/certs/mcp.pem;
    ssl_certificate_key /etc/nginx/certs/mcp.key;
    location /mcp {
        proxy_pass http://kb_pool;
        proxy_http_version 1.1;
        proxy_set_header Host $host;  # Host 原样透传,供后端校验
        proxy_buffering off;          # SSE 流不落缓冲
        proxy_read_timeout 3600s;     # 长工具调用不掐线
    }
}

解读:Mcp-Method、Mcp-Name 这类自定义头 nginx 默认原样透传,后端收得到;第 2 篇讲头路由的价值在这里兑现——想按工具分流,加一段 map $http_mcp_name 就能把高频工具指到专属后端,代理全程不必解析正文。proxy_buffering off 与放长的 proxy_read_timeout 是 SSE 场景的标配,否则流式响应会被缓冲、长调用会被默认 60 秒超时掐断。TLS 在代理终结时,后端要认转发头:改用 streamable_http_app() 自起 uvicorn 时加 --proxy-headers --forwarded-allow-ips,否则重定向会生成 http:// 地址,HTTPS 客户端拒绝降级。客户端接入端,宿主一条命令挂上:claude mcp add --transport http kb https://mcp.example.com/mcp,旧的 --transport sse 已被官方标记废弃,详见 Claude Code 的 MCP 文档。

6、传输安全边界

两种传输的安全模型完全不同,边界画对位置才谈得上防护。stdio 的边界就是进程权限:server 以你的用户身份运行,能读写你的文件、用你的网络凭证、读注入的环境变量,而驱动它的是模型——装一个不可信的 server,等于把一个 shell 交给它背后的人。纪律三条:只装可信来源的 server;配置里的 env 字段是明文存盘的,密钥能不给就不给;高敏环境把进程关进容器或专用账号里降权。

HTTP 一侧,默认防护的适用范围容易被误解。源码逻辑是:只有当 host 是 localhost 系地址且未显式传参时,才自动开启 DNS 重绑定(DNS rebinding)防护、只放行本机 Host;换成 0.0.0.0 或公网地址又不显式传 transport_security,防护整体关闭——监听面变大的那一刻,默认防线反而撤了。生产三件套:TLS(上一节的代理终结)、Host 与 Origin 白名单(TransportSecuritySettings(allowed_hosts=[...], allowed_origins=[...]),非法 Host 得 421、非法 Origin 得 403)、再上一层认证令牌——claude mcp add --transport http 的 --header "Authorization: Bearer ..." 就是客户端侧的样子,令牌怎么发怎么验,是第 7 篇的主题。

stdio 的安全边界就是你自己的账号:模型能做什么,取决于拉起进程的人给了它什么。

7、实战:知识库上容器

把第 3 篇的知识库 server 从 stdio 升级成“容器 + Streamable HTTP”,总共三步。第一步改启动参数,kb.py 的尾部换成如下写法。

from mcp.server.transport_security import TransportSecuritySettings

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",       # 容器内必须监听全部网卡
        port=8000,
        stateless_http=True,  # 旧客户端请求也不落会话
        transport_security=TransportSecuritySettings(
            allowed_hosts=["mcp.example.com", "mcp.example.com:*"],
            allowed_origins=["https://app.example.com"],
        ),
    )

解读:host="0.0.0.0" 是容器硬要求;上一节说过它会把默认防护一起撤掉,所以 transport_security 必须显式带上,域名按实际访问入口填,带端口通配的两种写法都要列。第二步写 Dockerfile,如下。

FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen          # 依赖单独成层,改代码不重装
COPY kb.py ./
COPY docs/ docs/
EXPOSE 8000
CMD ["uv", "run", "--frozen", "kb.py"]

解读:基础镜像自带 uv;依赖层只拷 pyproject.toml 与 uv.lock,uv sync --frozen 严格按锁文件安装,与第 5 篇“钉版本”的口径一致;docs/ 语料一并打进镜像,语料常换就改成挂载卷。第三步构建、运行、接入,命令如下。

docker build -t kb-mcp .
docker run -d --name kb-mcp -p 8000:8000 kb-mcp
claude mcp add --transport http kb http://127.0.0.1:8000/mcp

解读:本机先用 http 冒烟——第 3 节那条 curl 原样能打通,服务就是健康的;上生产套第 5 节的 nginx 与 TLS,把接入命令换成 https://mcp.example.com/mcp。第 5 篇的 pytest 套件在这个镜像上照常可跑,协议回归网不断。

8、总结

传输层的工程图景收拢成几句话:官方传输只剩 stdio 与 Streamable HTTP,本地个人工具选前者——进程即会话、stdout 即协议线;跨机器服务选后者——单端点 POST、每请求自描述。run(transport="streamable-http") 两行起服务,curl 带上 MCP-Protocol-Version、Mcp-Method、Mcp-Name 与双 Accept 即可冒烟;会话只属于旧时代客户端,stateless_http 只作用于旧路径,现代请求天然无状态,轮询扩容随便铺。容器里记得 0.0.0.0 加显式安全设置,代理侧透传头、关缓冲、放长超时。留三道练习:

  • 用 curl 发一条 Mcp-Method 与正文不一致的请求,观察 HeaderMismatch 报文
  • 把知识库起两个实例挂 nginx 轮询,验证现代请求不需要粘性路由
  • 给镜像加一条 @mcp.custom_route("/health", methods=["GET"]) 健康路由,接入容器编排探活

对于手里已有 stdio server 的读者,建议照第 7 节的三步走:改 run()、写 Dockerfile、curl 冒烟,半天就能把个人工具升级成团队服务。认证、授权与多租户的完整方案,本系列第 7 篇展开。

相关推荐

​Jev 详解:不做生成的判断模型
精选AI

​Jev 详解:不做生成的判断模型

Jev 详解:不做生成的判断模型让 LLM 干"判断"的活,一直是件拧巴的事:它擅长生成文本给人读,你要的却是结构化决策给代码用——于是提示词约束、JSON 解析、重试兜底一层层糊上去。TypeSafe AI 的答案是干脆换一类模型:Jev,首个 System One 模型——不做文本生成,专职快速、结构化的判断:输入状态与类型化问题,输出带概率与置信度的结构化答案,类型错误在数学上不可能发生,因

762
网站被注入恶意脚本排查实录:AI 辅助安全分析实战
置顶 精选AI

网站被注入恶意脚本排查实录:AI 辅助安全分析实战

网站被注入恶意脚本排查实录:AI 辅助安全分析实战某天收到华为云监管反馈,称个人博客网站存在色情违规界面。作为技术博主,这简直是晴天霹雳——网站一直正常运行,怎么会突然出现这类问题?经过排查发现,网站被注入了恶意跳转脚本。本文记录完整的排查过程,重点分享如何借助 AI 快速定位问题并修复,希望能给遇到类似情况的开发者提供参考。1、问题发现与初步排查收到监管反馈后,第一时间打开网站检查。首页看起来完

451
博客七周年:AI 一天完成整体重构
全站置顶 精选AI

博客七周年:AI 一天完成整体重构

博客从 2019 年国庆用 Xiuno BBS 搭建,到 2026 年国庆整整七年。868 篇文章、53 条评论、6060 个代码块,这次与 AI Agent 结对,一天完成从 PHP 论坛到 Next.js 的整体重构与无损迁移。

430