SpringAI的MCP改STREAMABLE怎么配

Spring AI 2.x 起，MCP Server Boot Starter 文档里 SSE WebMVC / SSE WebFlux 两行都标了 deprecated since 2.0.0, use STREAMABLE instead 。现场常见症状不是「服务起不来」，而是：依赖还是熟悉的 spring-ai-starter-mcp-server-webmvc（或 webflux），YAML 仍写旧 SSE 协议语义，升级 BOM 后文档已切到 Streamable-HTTP，值班却还在搜「SSE 端点怎么配」「message endpoint 还在不在」。

本稿只做 protocol / transport 增量 ：同 starter，把 spring.ai.mcp.server.protocol 改成 STREAMABLE ，默认端点 /mcp ，可选改 streamable-http.mcp-endpoint。MCP 概念、工具注册、注解扫描等全景见站内已发文，本稿不复写；也不展开 Advisors 主线。读完应能独立完成一次「弃用警告消失 + POST 打到正确 path」的冒烟。

一、现象：SSE 弃用，文档已切 STREAMABLE

升级到 Spring AI 2.0.0 及以后 （以 BOM / 文档当时版本为准，勿钉死 patch）后，对照官方 MCP Server Boot Starter 协议表，通常会看到三类信号叠在一起：

SSE WebMVC / SSE WebFlux 标注 deprecated since 2.0.0，引导改用 STREAMABLE；
Streamable-HTTP 专页写明它 replaces the SSE transport；
示例配置里出现 spring.ai.mcp.server.protocol=STREAMABLE，端点默认落到 POST /mcp。

值班容易踩两种坑。一是「只升 BOM、不改 protocol」：依赖树已到 2.x，配置仍按旧 SSE 语义，文档却在推 STREAMABLE。二是「以为要换一套全新 artifact」：看到 Streamable 就去搜带 streamable 的 starter 名，反而忽略官方表与 XML 仍落在 webmvc / webflux 两条坐标上。

注意口径：弃用 ≠ 已删除。文档写的是 deprecated + 改用 STREAMABLE，没有要求立刻把旧 SSE 配置从仓库物理抹掉才能编译。迁移清单应写成「协议切到 STREAMABLE」，而不是「SSE 模块没了所以装不上」。别写成「SSE 已删除不可用」------那是误读。

与全景主文的边界：Spring AI MCP 全景讲概念与工具侧；本稿只补 怎么把传输协议改到 STREAMABLE。LangChain4j Boot4 starter 换后缀是另一条框架线，勿和 MCP protocol 混进同一张「随便改个坐标」清单。

二、开关：protocol=STREAMABLE（全大写）

启用 Streamable 时，属性名与取值必须按文档写死大小写------现场一半「配了不生效」来自枚举大小写或属性路径写短了。

properties 复制代码

spring.ai.mcp.server.protocol=STREAMABLE

项	正确写法	易错写法（勿用）
属性全名	`spring.ai.mcp.server.protocol`	`spring.ai.mcp.protocol`、`mcp.server.protocol` 等自创短写
取值	`STREAMABLE`（全大写）	`streamable` / `Streamable` / `STREAMABLE_HTTP`

官方表里同风格还有 SSE、STATELESS 等------枚举按表抄，不要凭感觉造词。专页也写明：Must be set to STREAMABLE to enable the streamable server。YAML 里写成 protocol: STREAMABLE 与 properties 等价，关键仍是 全大写 STREAMABLE。

同 starter、改 protocol 即可，不必另装一套「streamable 专用主依赖」：

评审 PR 可用一条廉价规则：全文搜 mcp.server.protocol，确认右侧是精确的 STREAMABLE；再搜旧 SSE 相关注释，避免「代码已切、README 还在教 SSE 端点」的半迁移。

三、Starter：WebMVC / WebFlux 二选一

Streamable-HTTP 与 SSE / STATELESS 共用同一对 HTTP starter，靠 protocol 区分传输语义。这是和「以为要换 artifact」最容易打架的一点：

栈	groupId	artifactId
Servlet / WebMVC	`org.springframework.ai`	`spring-ai-starter-mcp-server-webmvc`
Reactive / WebFlux	`org.springframework.ai`	`spring-ai-starter-mcp-server-webflux`

STDIO 另用 spring-ai-starter-mcp-server（无 webmvc/webflux 后缀），与本文 HTTP Streamable 路径分开即可，勿混进同一「随便换个 starter」清单。

Maven 示意（版本以 Spring AI BOM / 文档当时为准，勿钉死）：

xml 复制代码

<!-- WebMVC：与 SSE 时代同一 artifact，靠 protocol 切 STREAMABLE -->
<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
  <!-- 版本：跟随 spring-ai-bom / 文档当时，勿写死 patch -->
</dependency>

Gradle Kotlin DSL 同理，只换坐标家族里的 artifact 后缀语义（webmvc ↔ webflux），版本仍交给 BOM：

kotlin 复制代码

dependencies {
    // 版本跟随 spring-ai-bom；勿在业务模块钉死 patch
    implementation("org.springframework.ai:spring-ai-starter-mcp-server-webmvc")
}

WebFlux 把 artifactId 换成 spring-ai-starter-mcp-server-webflux 即可。选型口诀：

工程已是 Spring MVC → webmvc starter + protocol=STREAMABLE；
工程已是 WebFlux → webflux starter + 同一属性；
不要 WebMVC / WebFlux 双 starter 同时当主路径硬叠；
文档 yaml 注释里若出现过带 streamable 字样的 artifact 名，表与 XML 依赖仍以 webmvc / webflux 为准------勿把注释名写成唯一必装坐标。

半迁移提醒：只改了 protocol、却仍保留「客户端按旧 SSE 握手路径探测」的脚本，冒烟会表现为「服务端已 STREAMABLE，客户端还在找旧 path」。协议与客户端探测路径要同一轮改，别拆成两个互不等待的 PR。

四、端点：默认 `/mcp`，可配 mcp-endpoint

Streamable-HTTP 属性前缀是 spring.ai.mcp.server.streamable-http 。其中 mcp-endpoint 表示自定义 MCP 路径，默认 /mcp 。总文档 Securing 节也写默认 POST /mcp 。把默认 path 记成 /sse 或臆造 /mcp/message，是另一类高频误读------以文档表 Default=/mcp 为准。

最小配置（保持默认 path）：

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE
        # streamable-http.mcp-endpoint 默认为 /mcp，可省略

自定义 path 示例（文档同构示意，可改为 /api/mcp 等）：

yaml 复制代码

spring:
  ai:
    mcp:
      server:
        protocol: STREAMABLE
        streamable-http:
          mcp-endpoint: /api/mcp

properties 等价写法：

properties 复制代码

spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.streamable-http.mcp-endpoint=/api/mcp

冒烟时优先打 POST 到配置后的端点，别去猜旧 SSE 时代的 path。网关或反向代理若做了 path rewrite，确认对外路径与 mcp-endpoint 一致，避免「容器内 /mcp 通、公网 404」的伪失败。

安全边界一句：官方写明 HTTP 传输下 MCP 端点 默认无鉴权；出 localhost / 内网演示环境前，须自行加网关、Spring Security 或等价边界，别把「能 curl 通」当成生产就绪。本稿不展开 Security 过滤器链------那是安全专题，不是 protocol 增量的职责。

迁移检查清单（适合塞进升级 PR 描述）：

spring.ai.mcp.server.protocol 是否为 STREAMABLE（全大写）；
starter 是否为 ...-webmvc 或 ...-webflux 之一，且未发明必选 streamable 专用主依赖；
端点是否按默认 /mcp 或已显式配置 streamable-http.mcp-endpoint；
客户端 / 探测脚本是否同步切到新 path，而非仍扫旧 SSE 路径；
版本是否跟随 BOM/文档，注释是否标明「勿钉死」；
出公网前是否已补鉴权（默认无鉴权）。

五、怎么验：弃用警告消失 + POST 打到 /mcp

验收不必先上完整工具链，先做传输层冒烟即可：

配置侧 ：启动日志或 Actuator/配置打印中确认 protocol 已是 STREAMABLE（若你们有统一配置导出）。
依赖侧 ：依赖树里是 spring-ai-starter-mcp-server-webmvc 或 ...-webflux，没有「为了 Streamable 又叠了一套未文档化主坐标」。
HTTP 侧 ：对默认或自定义 endpoint 发 POST ；path 与 mcp-endpoint 一致。
文档侧 ：团队内部 runbook 删除「去配 SSE 端点」的过时步骤，改写为 STREAMABLE + /mcp。

若仍看到与 SSE deprecated 相关的提示，优先查是否还有第二份配置源（application-*.yml、本地 override、测试用 DynamicPropertySource）把 protocol 盖回旧值。配置优先级问题比「是不是缺一个神秘 starter」更常见。

工具注册、业务 Tool 回调是否成功，属于全景文与业务验收范围；传输协议切对之后，那些用例才有稳定复现的前提。别在 protocol 未切完时，把工具注解扫描失败误判成「STREAMABLE 配错了」。

六、FAQ

Q1：SSE 为什么弃用？还要不要删依赖？

A：自 2.0.0 起官方表标注 SSE deprecated，改用 STREAMABLE；Streamable-HTTP replaces the SSE transport 。口径是协议迁移，不是「SSE 已删除、旧 starter 装不上」。同 webmvc/webflux starter，改 protocol 即可。评审时禁止把「deprecated」口头传成「deleted」。

Q2：STREAMABLE 怎么开？

A：设置 spring.ai.mcp.server.protocol=STREAMABLE（全大写）。专页要求 Must be set to STREAMABLE。不要写成 streamable、Streamable 或自创 STREAMABLE_HTTP。YAML 与 properties 两种写法都行，枚举大小写不能错。

Q3：WebMVC / WebFlux starter 怎么选？

A：跟应用栈走------MVC 用 spring-ai-starter-mcp-server-webmvc，WebFlux 用 ...-webflux。二者与 SSE 时代共用 artifact，靠 protocol 区分。STDIO 用无后缀的 spring-ai-starter-mcp-server。勿把 yaml 注释里偶发出现的 streamable 字样 artifact 当成唯一必装。

Q4：默认端点是什么？怎么改？

A：默认 /mcp （POST）。改 path 用 spring.ai.mcp.server.streamable-http.mcp-endpoint。不要臆造其它默认 path（如把 /sse 当 Streamable 默认）。网关 rewrite 时对外 path 与配置保持一致。

Q5：版本写死哪个？和 166641101 什么关系？

A：版本以 Spring AI BOM / 官方文档当时为准；文中只锚「2.0.0 起 SSE deprecated」。全景与工具注册见 166641101；本稿仅 protocol/transport 增量，不重写 MCP 长文，也不写 Advisors 主线。

Q6：只改 protocol 够不够？还要不要动业务代码？

A：对「传输协议从 SSE 语义迁到 STREAMABLE」这一刀，配置 + 同 starter 通常足够。业务 Tool 实现、鉴权过滤器、网关路由属于相邻变更：协议切完再单独验收，避免一个巨型 PR 里既改坐标又重写工具层，出问题难定位。

七、小结

Spring AI MCP 改 STREAMABLE，轻量路径可以压成四步：

认弃用 ：SSE deprecated since 2.0.0，改 STREAMABLE；禁说「已删除」。
改协议 ：同 spring-ai-starter-mcp-server-webmvc / ...-webflux，设 spring.ai.mcp.server.protocol=STREAMABLE（全大写）。
验端点 ：默认 /mcp ；需自定义再配 streamable-http.mcp-endpoint；客户端探测同步改。
补边界：HTTP 默认无鉴权，出网前自行加安全措施。

把「protocol 是否已是 STREAMABLE、端点是否还在猜旧 SSE path、README 是否仍教 SSE」写进升级 Definition of Done，比在日志里反复搜 deprecated 关键字便宜。概念与工具侧继续走全景主文；本稿只保证传输协议这一刀切干净。

落地时把「协议枚举」和「端点 path」拆成两次核对：一次只看 STREAMABLE 是否写对，一次再看 /mcp 或自定义 endpoint 是否与网关一致。混在同一巨大变更里，评审很容易只盯 starter 坐标，漏掉仍残留的旧协议值。

SpringAI的MCP改STREAMABLE怎么配