外部工具接入通道选择（Claude Code MCP 四种传输类型）

业务里第一次要把 Sentry、Notion、PostgreSQL 接进 Claude Code 时，最容易卡住的不是”装不装得上”，而是”该用哪种传输”。在一次 MCP（Model Context Protocol）接入中，我们把同一个 GitHub 服务先后跑了 stdio 与 HTTP 两种通道：前者必须在每台开发机本地起子进程，团队成员各自维护一份密钥；后者直接走云端 URL，OAuth 流程跑完即用。把这次对比展开成方法论，核心问题就是——MCP 协议当前支持的几种传输类型、它们各自适用什么场景，以及其中已被官方标记为 deprecated 的那种具体是哪一种。

一、MCP 在 Claude Code 中的角色

MCP 是一个开放标准，由 Anthropic 在 2024 年 11 月开源、并在 2025 年 12 月捐赠给 Linux 基金会下属的 Agentic AI 基金会。它被形象地比作”AI 的 USB-C 接口”：任何 AI 应用只要按这套协议实现客户端，就能接入任何按协议实现的服务器端能力，连接外部数据源与工具的”N×M 难题”被压缩成”N+M”。

Claude Code 在这套体系里扮演 Host 角色：

Host：AI 应用本体的协调层，负责任务编排、上下文管理与用户授权。Claude Code、Claude Desktop、VS Code、Cursor 都属于 Host。
Client：Host 内部为每个 MCP 服务器创建的独立连接器，1 个 Client 对应 1 个 Server。
Server：对外暴露能力（tools、resources、prompts）的程序，形态可以是本地脚本，也可以是远程云服务。

Host 与 Server 之间真正传消息，靠的是传输层。Claude Code 当前支持的传输类型共有 4 种，其中 1 种已被标记为 deprecated。

二、四种传输类型总览

下表从通道类型、部署位置、典型用途、推荐程度四个维度把四种传输摆在一起对照：

传输类型	通道形式	部署位置	典型用途	当前推荐度
stdio	标准输入/输出	本地子进程	文件系统、本地数据库、自定义脚本	推荐
http（streamable-http）	HTTP POST + 可选 SSE	远程服务	SaaS 集成（Notion、GitHub、Sentry）	推荐（远程首选）
sse	HTTP + Server-Sent Events	远程服务	旧版远程服务器兼容	已 deprecated
ws	WebSocket	远程服务	长连接、双向通信	通过 JSON 配置启用（不暴露 CLI 标志）

四个通道在协议层都跑 JSON-RPC 2.0，差别仅在”消息怎么从 Client 走到 Server”。

三、stdio：本地子进程通道

stdio 是 MCP 协议的”原始”通道。Claude Code 把 MCP 服务器作为子进程拉起，把 JSON-RPC 消息写到 stdin，从 stdout 读回响应；服务器日志走 stderr，由 Claude Code 捕获展示。

适用场景：

需要直接访问本机文件系统的工具（文件读写、本地编译器封装）。
自定义脚本型服务器（Python/Node 写的轻量封装）。
不想让凭据经过网络的本地凭据型服务（数据库密码、本地 Token）。
开发与自测自己的 MCP 服务器。

局限：stdio 服务器天然绑定单台机器，团队成员无法共享同一进程实例；stdiod 进程崩溃后 Claude Code 不会自动重连，需要手动重启。

CLI 用法：

claude mcp add --transport stdio \
  --env AIRTABLE_API_KEY=${AIRTABLE_API_KEY} \
  airtable -- npx -y airtable-mcp-server

.mcp.json 配置示例（type: "stdio" 时可不写 type，缺省即 stdio）：

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

关键细节：stdio 模式下，Claude Code 会向子进程注入 CLAUDE_PROJECT_DIR（项目根目录），比依赖当前工作目录更可靠——尤其是会话中执行过 cd 之后。

四、http（streamable-http）：远程服务推荐通道

HTTP（也写作 streamable-http，规范名是 streamable-http，Claude Code 同时识别 http 与 streamable-http 两种写法）是当前远程 MCP 服务器的默认推荐通道。它在 MCP 协议 2025-03-26 版本中引入，并在 2025-06-18 修订中完善，单一端点同时支持 POST 请求与 GET 触发的 SSE 流。

相对旧版 SSE 的关键改进：

单端点：取代过去 GET 拉流 + POST 发消息的双端点结构。
会话管理：通过 Mcp-Session-Id 头管理会话状态。
可恢复流：用事件 ID 标记流断点，便于断线续传。
协议版本协商：MCP-Protocol-Version 头显式协商。

适用场景：所有云端 SaaS 集成、团队共享的远程服务、任何需要跨机器访问的服务器。

CLI 用法：

claude mcp add --transport http notion https://mcp.notion.com/mcp

.mcp.json 配置示例：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

HTTP 通道原生支持三种认证模式：静态 API Key（写到 headers）、OAuth 2.0（远程服务器的标准流程）、动态 headers（通过 headersHelper 脚本在连接时生成短期 Token）。HTTP 通道还具备自动重连能力：连接断开后从 1 秒起指数退避，最多重试 5 次；初始连接遇 5xx、连接拒绝、超时最多重试 3 次；认证失败与 404 不重试。

五、sse：已被标记为 deprecated 的旧通道

SSE（Server-Sent Events，HTTP+SSE 传输）来自 MCP 协议 2024-11-05 版本，结构上由两个独立端点组成：GET 端点打开 SSE 长流接收消息，POST 端点接收 JSON-RPC 请求。Claude Code 与 MCP 官方均明确将其标记为 deprecated——Claude Code 文档原话是”已被标记为 deprecated”，并建议”除非目标服务只提供 SSE，否则优先使用 HTTP”。

为什么被淘汰：

双端点结构复杂，部署与排障成本高。
没有标准化的会话恢复机制，断线重连要靠客户端自行实现。
与 streamable-http 在能力上重复，且后者更易扩展。

仍存在的原因：仍有部分老牌 SaaS 暂时只暴露 SSE 端点。在 Claude Code 中仍可通过 claude mcp add --transport sse 与 type: "sse" 兼容接入，但属于过渡方案，不应再用于新接入。

过渡用 CLI：

claude mcp add --transport sse asana https://mcp.asana.com/sse

{
  "mcpServers": {
    "asana": {
      "type": "sse",
      "url": "https://mcp.asana.com/sse"
    }
  }
}

六、ws：WebSocket 通道

除上述三种主流通道外，Claude Code 还支持 WebSocket（ws）传输。WebSocket 在 MCP 协议中作为长连接双向通道存在，适合需要服务端主动、持续、双向推送消息的场景。

需要注意的限制：WebSocket 不支持 claude mcp add --transport CLI 标志——必须用 claude mcp add-json 或直接编辑 .mcp.json。另外，因为只有 HTTP 通道支持 OAuth 与 --transport 标志，WebSocket 通常不作为远程默认选项，但在需要长连接与双向实时性的场景下仍是合理选择。

.mcp.json 配置示例：

{
  "mcpServers": {
    "realtime-feed": {
      "type": "ws",
      "url": "wss://mcp.example.com/realtime"
    }
  }
}

七、选型决策清单

把传输选择落地成可执行步骤：

先判断部署位置：能跑在同一台机器就 stdio；跨机器就 HTTP，WebSocket 仅在需要长连接双向通信时考虑。
远程服务默认 HTTP：除非服务端只暴露 SSE，否则不要选 sse。
认证方式优先 OAuth：HTTP 通道对 OAuth 支持最完善；本地方案用环境变量注入 Token。
scope 与传输配套：local scope 配 stdio，project scope 配 HTTP（团队共享），user scope 放个人常用远程。
监控断线与重连：HTTP 通道自动重连覆盖 5xx 与超时；stdiod 进程崩溃后必须手动重启。

八、几个常被忽略的细节

type 字段不写时默认 stdio，因此省略 type 也能跑本地服务器。
http 与 streamable-http 是同一件事——两种字符串在 Claude Code 中完全等价，按个人偏好选用。
scope 的优先级：local > project > user，相同名字的服务器按优先级全条目替换，不会按字段合并。
插件内置 MCP：插件可以自带 MCP 服务器，启用插件后自动拉起，无需手动配置。
Channels 与 MCP 是不同概念：Channels 是 MCP 服务器通过 claude/channel capability 主动向会话推送消息的机制，与传输类型正交。

到这里，MCP 的传输选型就有了一条清晰的决策路径：本地脚本走 stdio，远程服务走 HTTP（streamable-http），旧 SaaS 兼容用 SSE，特殊长连接场景才考虑 WebSocket。下一阶段真正要解决的，是不同传输之间在能力协商、断线重连、OAuth 流程上的差异细节，以及与 Channels、Plugins 协同后的整体配置管理。

常见问题（FAQ）

Q1：四种传输里哪一种已 deprecated？

SSE（HTTP+SSE）已被官方明确标记为 deprecated，新接入应直接用 streamable-http。

Q2：本地服务能用 HTTP 通道吗？

技术上可以，但 stdio 通道更轻、零网络开销，本地服务器优先选 stdio。

Q3：HTTP 通道断了会自动重连吗？

会自动重连，指数退避最多 5 次；stdiod 进程崩溃则不会自动重连，需要手动重启。