MCP 传输方式：STDIO、SSE、Streamable-HTTP

30.1 传输方式是什么

传输方式决定 MCP 客户端和服务器之间的消息怎么走。协议内容一样，走的”管道”不同。Spring AI 支持四种：STDIO、SSE、Streamable-HTTP，以及 Streamable-HTTP 的 Stateless（无状态）变体。

选传输方式主要看两个问题：服务器部署在哪，以及需不需要双向通信。

先看通信方向。MCP 有两种消息流向：客户端发起请求（单向），和服务器主动推送（双向）。STDIO 只有请求响应，Streamable-HTTP 还支持服务器推送。再看部署形态：本地进程还是独立服务。两个问题答案定了，选择基本就定了。

30.2 STDIO：本地进程管道

STDIO 用标准输入输出通信。客户端启动服务器进程，把 JSON-RPC 消息写到服务器的标准输入，从标准输出读响应。

特点是简单、零网络开销、没有端口和防火墙问题。缺点是服务器不能独立运行，只能被客户端拉起，且一次只能服务一个客户端。

适合命令行工具、桌面应用集成本地能力。配置只要一个开关：

spring:
  ai:
    mcp:
      server:
        stdio: true

客户端侧要指定启动命令和参数，见 30.7 的速查配置。Windows 上运行 npx 这类批处理命令时，要加 cmd.exe /c 包装，第 28 章讲过，不重复。

30.3 SSE：被取代的流式方案

SSE（Server-Sent Events）是 HTTP 上的单向流。客户端先连 /sse 端点建立事件流，再通过 /mcp/message 端点发消息。服务器可以主动向客户端推送事件，支持多客户端连接。

SSE 的缺点是端点分两个、连接管理复杂。客户端要先 GET /sse 等事件流，再 POST /mcp/message 发消息，两边要配合好，部署时还要把两个端点都暴露出去。MCP 规范在 2025-03-26 版本引入 Streamable-HTTP 后（见 modelcontextprotocol.io 规范），SSE 就被取代了。Spring AI 从 2.0 起把它标记为弃用，官方建议新项目一律用 STREAMABLE。老项目还在用，了解配置即可：

spring:
  ai:
    mcp:
      server:
        protocol: SSE

30.4 Streamable-HTTP：当前主流

Streamable-HTTP 取代 SSE 成为 HTTP 部署的标准。它只需要一个端点（默认 /mcp），客户端用 POST 发请求，用 GET 建立可选的事件流接收服务器消息。

相比 SSE 的两端点设计，部署简单很多。它还支持服务器主动推送，工具、资源、提示词列表变化时能及时通知客户端。配置：

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE

它适合需要多客户端、需要变更通知的独立服务，是 HTTP 部署的默认选择。

还有两个实用配置。mcp-endpoint 自定义端点路径，默认 /mcp；keep-alive-interval 开启心跳，服务器定期 ping 客户端确认连接健康，默认关闭。心跳只对 SSE 监听连接生效，普通请求响应不需要。

30.5 Stateless：无状态变体

Stateless Streamable-HTTP 不维护会话状态，每个请求独立处理。没有会话黏性，水平扩容毫无负担，特别适合微服务、云原生部署。

代价是能力受限。服务器不能给客户端发消息，elicitation（向用户追问信息）、sampling（请求 LLM 采样）、ping 都不支持。工具方法里也不能用 McpSyncRequestContext 这类依赖双向通信的参数，只能用轻量的 McpTransportContext。

配置：

spring:
  ai:
    mcp:
      server:
        protocol: STATELESS

如果你的工具只是”请求进来、结果出去”，不需要服务器主动联系客户端，Stateless 就是最省事的选择。

实践里不少团队把 Stateless 部署在 Kubernetes 上，副本随便扩，前面挂负载均衡，不需要会话亲和性。代价是前面说的能力限制，开发时方法里别用 McpSyncRequestContext，改用 McpTransportContext，或者干脆不用上下文参数。

30.6 四种方式对比

维度	STDIO	SSE	Streamable-HTTP	Stateless Streamable-HTTP
部署形态	客户端拉起子进程	独立 HTTP 服务	独立 HTTP 服务	独立 HTTP 服务
端点	无（标准输入输出）	/sse + /mcp/message	/mcp（可配）	/mcp（可配）
多客户端	单客户端	支持	支持	支持
会话状态	有	有	有	无
服务器主动推送	不支持	支持	支持（可选 SSE 流）	不支持
双向操作（sampling 等）	支持	支持	支持	不支持
服务端属性	stdio=true	protocol=SSE	protocol=STREAMABLE	protocol=STATELESS
2.0 状态	支持	已弃用	推荐	推荐

选型建议：

本地工具集成，选 STDIO。零部署成本，但只能本机用。

需要独立服务、多客户端访问，选 Streamable-HTTP。这是新项目默认，功能最全。

需要无状态水平扩容，选 Stateless。前提是工具不需要双向通信。

已经上了 SSE 的老项目，升级时顺手迁到 STREAMABLE 就行，配置只改一个值。客户端连接方式也基本不用动，都是 HTTP 服务。

30.7 客户端配置速查

服务器端定好传输方式，客户端对应配置：

spring:
  ai:
    mcp:
      client:
        stdio:
          connections:
            local-server:
              command: java
              args: ["-jar", "my-server.jar"]
        sse:
          connections:
            sse-server:
              url: http://localhost:8080
        streamable-http:
          connections:
            http-server:
              url: http://localhost:8080

SSE 默认访问 /sse，Streamable-HTTP 默认访问 /mcp。服务器改了端点，客户端用 sse-endpoint 或 endpoint 跟随。

30.8 常见问题

几个高频问题，按传输方式归类。

STDIO 连不上：先手动跑启动命令验证程序本身，再检查 Windows 上有没有加 cmd.exe /c 包装。

SSE 报 404：多半是 url 拆分不对。base url 只放协议、域名、端口，完整路径放进 sse-endpoint。

Streamable-HTTP 工具列表为空：确认服务器 protocol 是 STREAMABLE 而不是默认值，确认客户端 endpoint 和服务器 mcp-endpoint 一致。

Stateless 调用报错：检查工具方法是否用了 McpSyncRequestContext 这类双向上下文参数，Stateless 不支持，换 McpTransportContext 或去掉参数。

30.9 小结

四种传输：STDIO 走本地进程管道，SSE 已弃用，Streamable-HTTP 是主流，Stateless 是无状态变体。选型看两点：本地还是远程、要不要双向通信。配置层面，服务器端用 stdio 开关或 protocol 属性，客户端按传输类型配连接。