第 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") 的旧入口仍在,同样只为兼容存量。怎么选,决策链如下。
解读:判定的第一问是“客户端在哪”。个人工具、读本地文件、操作本机环境——宿主就在同一台机器上,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 篇展开。

