Spring AI MCP Server SSE 端点无法访问：3 种解法 + 完整避坑清单
【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai
凌晨一点的调试现场：服务启动日志干干净净，浏览器敲localhost:8080/sse，页面空白；换成 Postman 发 GET，连接转圈到底也没个回音——这个端点像黑洞，把所有请求都吞了，控制台一行错误都不给。折腾一圈后发现，Spring AI 的 MCP Server SSE 端点访问失败，问题出在三处：依赖版本混用、webflux 没开 reactive 模式、webmvc 与 webflux 同时引入。最省事的一条路是切到 webmvc 依赖，立等可取。
读完这篇能拿走 3 个直接可上手的解法和 1 份上线前必查清单，全程不超过十分钟。
30 秒分流：你的故障落在哪一格？
SSE（Server-Sent Events）是服务端向客户端单向推流的 HTTP 长连接，MCP Server 靠它把消息持续推给客户端。你的症状对号入座，直接跳到对应章节：
| 你的情况 | 大概率原因 | 看哪节 |
|---|---|---|
| pom 里同时出现 1.0.0-M6 和 1.0.0-M7 两个版本的 Spring AI 组件 | 版本混用 | 根因一 |
| 依赖没混、服务也起了，但 /sse 永远挂着或 404 | webflux 没开 reactive | 根因二 |
| classpath 里 webmvc、webflux 两套 MCP Server 依赖都在 | 依赖冲突 | 根因三 |
SSE 端点无响应的 3 个根因
同步柜台和异步叫号，不是一回事
webflux 的 SSE 传输跑在响应式运行时（Netty 的非阻塞事件循环）上，webmvc 的跑在 Servlet 容器（Tomcat 的线程池）上。打个比方：webmvc 像窗口柜台，一个窗口同时只服务一个顾客，来了就办完为止；webflux 像大厅叫号，系统只负责喊号，不盯你取没取到。你的 Spring Boot 应用默认是"柜台模式"——此时就算 classpath 里塞了 webflux 的 SSE 端点 bean，也轮不到它们出场，请求打进来自然石沉大海，而且不报错。
30 秒验证：
curl -N -H 'Accept: text/event-stream' http://localhost:8080/sse命令挂住没输出，且应用日志显示 Tomcat started，基本就是这一条。
发动机和变速箱，不同批次
版本混用是典型的"M6 发动机配 M7 变速箱"。两个版本的 autoconfigure 类名、属性 key 都动过刀，混跑时自动装配的条件判断会互相错位：服务照起，端点路由却悄悄没挂上，日志里连个警告都不留。
30 秒验证：
mvn dependency:tree | grep spring-ai扫一眼版本号，M6、M7 两个批次同时出现就是它。
两套依赖抢一个柜台
webmvc 和 webflux 的 MCP Server starter 同时引入，Spring Boot 检测到 Servlet API 后按非响应式容器启动，webflux 那套自动配置直接静默失效。你看到的"端点不存在"，其实是配置压根没被激活。
30 秒验证：
mvn dependency:tree | grep mcp-server输出里同时出现 webmvc、webflux 两行，删掉一行再试。
三条修复路径（按推荐度降序）
路径 A：webmvc 最小依赖写法
最小改动：删掉 webflux，换 webmvc，一行依赖解决黑洞
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId> </dependency>重启后curl -N http://localhost:8080/sse立刻能看到event: endpoint推回来。为什么官方文档没这么写？文档习惯把响应式方案放在前面讲，但社区踩坑统计下来，默认非响应式的 Spring Boot 应用配 webmvc 反而零额外配置、最不容易翻车。
- 适用场景：绝大多数内部工具、单体后端服务。
- 已知副作用：webmvc 实现下，Spring Cloud Gateway 的转发链路不可用——它本身依赖 webflux 运行时。
路径 B：webflux 响应式配置方法
坚持 webflux 时，补上"叫号模式"的开关
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server-webflux</artifactId> </dependency>spring: main: web-application-type: reactive这两行让 Boot 切到 Netty 和响应式运行时，webflux 的 SSE 自动配置才真正生效。确认 classpath 里没有 webmvc 版本的 starter 和spring-boot-starter-web。
- 适用场景：团队统一响应式技术栈、高并发长连接服务。
- 已知副作用：OpenFeign 等基于 Servlet 的 HTTP 客户端在此模式下无法正常工作，需要换 Reactor Netty 一类的响应式客户端。
路径 C：webflux 完整配置参考
需要自定义端点和能力声明时的最小参考，5 个关键字段
spring: main: web-application-type: reactive ai: mcp: server: name: webflux-mcp-server type: ASYNC sse-endpoint: /sse sse-message-endpoint: /mcp/messages其中name、type、两个端点路径是必填核心，capabilities 声明按需追加即可，不建议照抄整份大配置。BOM 统一管版本，避免再次混批：
<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.1.0-SNAPSHOT</version> <type>pom</type> <scope>import</scope> </dependency>- 适用场景：对端点路径、服务器元数据有定制要求的外部服务。
- 已知副作用：与路径 B 相同——Feign 客户端不可用，网关后部署需单独验证转发。
避坑 Checklist
- BOM 统一管理版本：混用 M6/M7，端点静默消失
- webmvc、webflux 二选一：同时引入，自动配置失效
- 用 webflux 必开 reactive：不开，/sse 永远黑洞
- 上 webflux 前排查 Feign：客户端会直接罢工
- 端点路径别和网关冲突：转发规则可能吞掉 SSE
怎么选，下一步
内部工具、单体应用闭眼选路径 A，省事且社区验证最充分；对外提供高并发长连接服务、且团队本来就响应式，走 B 或 C。服务要挂在网关后面，先确认网关协议链路——webmvc 方案下 Gateway 转发不可用，必要时把 MCP Server 独立出口部署。
最后说句预期：这套 SSE 传输在 Spring AI 新版本里已标记为待移除，官方重心正转向 Streamable HTTP 传输，后续版本中本问题大概率被新架构自然消解。项目代码可直接从 GitHub_Trending/spr/spring-ai 仓库获取，对照 mcp/ 和 auto-configurations/mcp/ 目录能看懂两套传输的装配逻辑。
【免费下载链接】spring-aiAn Application Framework for AI Engineering项目地址: https://gitcode.com/GitHub_Trending/spr/spring-ai
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
