01 三种传输方式

01 三种传输方式

本节摘要:MCP(Model Context Protocol)让 Agent 标准化连接外部资源。本节讲 OpenCode 支持的三种 MCP 传输方式——stdio(本地子进程)、SSE(服务端推送)、流式 HTTP(现代双向流),它们各自适合什么场景、怎么选。理解了传输方式,你才知道「接一个 MCP server」时那条连接是走什么路的。

一、为什么有三种传输

MCP server 可以跑在各种地方——有的是本地命令(启动一个子进程)、有的是远程服务(通过 HTTP)。不同位置的 server,连接方式自然不同。MCP 协议定义了多种「传输(transport)」来覆盖这些情况,OpenCode 支持其中三种主流的。

二、三种传输一览

本地工具 ──► stdio(子进程 + 标准输入输出)
远程服务 ──► 流式 HTTP(优先)── 失败回退 ──► SSE
​

三、stdio:本地子进程

stdio 传输用于本地工具。你给 MCP 一个命令(如 npx 某MCP包),OpenCode 启动它作为子进程,通过它的标准输入(stdin)发请求、标准输出(stdout)收响应。

配置: { command: "npx", args: ["某MCP包"], cwd: "...", env: {...} }
   │
   ▼ OpenCode 启动子进程
子进程(某 MCP server)跑起来
   │
   ▼ stdin 发 MCP 请求 / stdout 收 MCP 响应
​

stdio 的好处是简单——不用开端口,子进程随 OpenCode 启停。适合「自带的小工具」(文件系统访问、本地命令执行、本地数据库)。

四、流式 HTTP:现代远程(优先)

对于远程 MCP server,OpenCode 优先用流式 HTTP(StreamableHTTP)。这是 MCP 协议的现代传输方式,基于 HTTP 的双向流,能很好地处理请求-响应和通知。

配置: { url: "https://某远程MCP服务/mcp" }
   │
   ▼ OpenCode 用流式 HTTP 连接
   │
   ▼ 双向流通通信
​

流式 HTTP 是远程连接的首选——它比 SSE 更现代、更适合 MCP 的通信模式。

五、SSE:老式远程(回退)

如果流式 HTTP 连不上(老式 server 不支持),OpenCode 回退到 SSE(Server-Sent Events)。SSE 是 HTTP 的服务端推送,老但兼容性好。

尝试连接远程 server:
   │
   ├─ 先试流式 HTTP ──► 成功就用它
   │
   └─ 失败 ──► 回退到 SSE
​

OpenCode 会按「流式 HTTP → SSE」顺序尝试。这样既优先用现代方式,又兼容老 server。

六、认证错误时的处理

有个细节值得注意:尝试连接时如果遇到认证错误(如 401),OpenCode 不会回退到下一种传输,而是停下来走 OAuth 流程(下一节)。因为认证错误意味着「这个 server 需要登录」,不是「这种传输不支持」。

尝试连接:
   │
   ├─ 流式 HTTP ──► 认证错误(401)──► 停下,走 OAuth(第 02 节)
   ├─ 流式 HTTP ──► 其他错误 ──► 试 SSE
   └─ SSE ──► ...
​

这种区分很细——认证问题用认证流程解决,传输问题用换传输解决,不混淆。

七、选型建议

给定一个 MCP server,怎么决定用哪种传输?

这个 server 是本地的(一个命令)吗?
   │
   ├─ 是 ──► stdio
   │
   └─ 否(远程 URL)
        │
        ├─ 让 OpenCode 自动选(优先流式 HTTP,回退 SSE)
        │
        └─ 大多数情况不用你操心,OpenCode 会试
​

💡 大多数情况不用手动选传输:配置 MCP 时你给命令(stdio)或 URL(远程),OpenCode 自动决定具体传输。只有排查连接问题时才需要关心用的是哪种。

八、连接状态机

不管哪种传输,连接后都会进入一个状态机,大致状态:

理解状态机有助于排查——「我的 MCP 没工作」时,先看它在哪个状态,状态指示了下一步该干什么(如 needs_auth 就去走认证)。

九、本节要点回顾

1. 三种传输:stdio(本地子进程)、流式 HTTP(远程优先)、SSE(远程回退)。
2. stdio:启动子进程,stdin/stdout 通信,适合自带本地工具。
3. 流式 HTTP 优先:现代双向流,远程首选。
4. SSE 回退:流式 HTTP 失败且非认证错误时回退到 SSE。
5. 认证错误走 OAuth:不换传输,停下来走认证流程(下一节)。
6. 大多自动选:给命令或 URL,OpenCode 自动定传输,排查时才需关心。
7. 状态机:connected/disabled/failed/needs_auth/needs_client_registration。

传输讲清了,下一节讲认证——MCP server 要登录时怎么办(OAuth 流程)。