Skip to content
Lv4MCP 协议进度 4 / 6

第 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)        # 不要用裸 print

print("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 两个地址,那是旧版。

两种传输,两条路径stdio:进程内的三根管道HostServerstdinstdoutstderr(日志)宿主拉起子进程;零网络;进程随宿主退出stdout 只放协议,一个 print 就能毁掉连接Streamable HTTP:一个端点ClientServerPOST /mcp请求JSON 或 SSE 流可远程部署;多客户端共享;可接 OAuth多了一层网络:超时、重连、鉴权都要自己管选型口诀:工具在本机 → stdio;工具在服务器、要给多个人用 → HTTP。一个 server 可以同时支持两种传输,取决于启动参数——第 5 章的代码会演示。

4.3 对比表 ​

维度stdioStreamable 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,带工具、资源、提示词,两种传输都支持。

本文阅读--次|全站访问--次|访客--人