第 4 章:两种传输:stdio 与 Streamable HTTP
协议消息是同一套 JSON,差别只在"怎么送过去"。选错传输,后面会一直别扭。
学习目标
- 说清 stdio 与 Streamable HTTP 各自的工作方式
- 知道 stdio 下"为什么不能随便 print"
- 会用官方 Inspector 在本地把 server 调通
- 按场景选对传输
4.1 stdio:宿主拉起的子进程
Host ──启动子进程──> Server(python server.py)
stdin ──JSON-RPC──> Server
stdout <──JSON-RPC── Server
stderr <──日志────── Server特点:
- 零网络,延迟最低;
- server 的生命周期跟着宿主走,宿主退出它就退出;
- 适合"本地工具":文件系统、本地数据库、本机脚本。
一条铁律:stdout 只能放协议消息,日志一律走 stderr。
python
import sys, logging
logging.basicConfig(stream=sys.stderr) # 关键
print("debug …", file=sys.stderr) # 不要用裸 printprint("debug") 默认写 stdout,会把一行调试信息插进协议流里,客户端解析 JSON 立刻失败。这是 stdio 模式最常见的崩溃原因,而且报错信息通常很含糊("invalid JSON"),很难联想到日志。
4.2 Streamable HTTP:一个端点,两种响应
Client ──POST /mcp──> Server
<──application/json 或 text/event-stream──工作方式:
- 客户端往同一个 HTTP 端点 POST JSON-RPC 消息;
- 服务端可以立刻返回 JSON,也可以返回
text/event-stream流式返回多条消息; - 客户端可以发一个
GET打开 SSE 通道,让服务端主动推送通知(比如资源变更)。
早期的 MCP 规范用的是"HTTP + SSE 双端点",后来的规范换成了 Streamable HTTP 这种单端点形式。看到老教程里的
/sse+/message两个地址,那是旧版。
4.3 对比表
| 维度 | stdio | Streamable HTTP |
|---|---|---|
| 部署 | 跟宿主同一台机器 | 任意位置,可远程 |
| 启动 | 宿主拉起子进程 | 你提前跑好服务 |
| 鉴权 | 靠操作系统权限 | 需要自己做(OAuth/token) |
| 多客户端 | 一个 server 进程一个连接为主 | 天然支持多客户端 |
| 延迟 | 最低(无网络) | 多一次 RTT |
| 调试 | 看 stderr | 看服务端日志 + 抓包 |
| 适合 | 文件、本地 DB、本机脚本 | 团队共享服务、SaaS、内部系统 |
4.4 用 Inspector 把它调通
官方提供了检查工具,能不写客户端就把 server 的手搓通:
bash
npx @modelcontextprotocol/inspector python server.py它会启动一个本地网页,界面上可以:
- 看
initialize协商出的能力; - 列出所有 tools / resources / prompts;
- 填参数直接调用,看返回的 content;
- 看原始 JSON 报文——这一步最有价值,能确认你的 schema 到底长什么样。
具体命令与界面随版本变化,以官方仓库说明为准。
如果你更喜欢自己写脚本,一个最小客户端也不难:起子进程、往 stdin 写 JSON、从 stdout 读一行。但调试阶段用 Inspector 省时间。
4.5 传输选择的三个判断
一条经验:先做 stdio 版本。它最小、最快、最容易调通,等真的需要给别人用时再包一层 HTTP。两者共用同一套工具定义,切换成本不高。
4.6 两个常见坑
| 坑 | 现象 | 修法 |
|---|---|---|
| stdout 混进日志 | 客户端报 JSON 解析失败 | 所有日志走 stderr |
| HTTP 没设超时 | 连接挂住、客户端假死 | 服务端与客户端都设读超时 |
忽略 nextCursor | 工具只看到一半 | 循环拉完分页 |
| 子进程路径不对 | 宿主启动失败、无日志 | 用绝对路径,先手动跑一遍 |
本章小结
| 要点 | 说明 |
|---|---|
| stdio | 子进程三根管道,零网络,最快 |
| 铁律 | stdout 只放协议,日志走 stderr |
| HTTP | 单端点 POST,可 JSON 或 SSE |
| 旧版 | HTTP+SSE 双端点已被 Streamable HTTP 取代 |
| 选型 | 本机 stdio,共享 HTTP |
| 调试 | Inspector 看原始报文 |
| 顺序 | 先 stdio,后 HTTP |
下一章
该动手了:用 Python 写一个真正能跑的 server,带工具、资源、提示词,两种传输都支持。