★ FEATURED ARTICLE 1. 从一次 404 说起Spring AI 接 MCP 到底卡在哪如果你正在用 Spring AI 接 MCP 服务大概率见过这个报错java.lang.RuntimeException: Unexpected status code: 404堆栈指向StreamableHttpMcpTransport。代码昨天还能跑今天换个依赖版本就 404很多人第一反应是服务端挂了其实服务端活得好好的问题出在协议版本对不上。MCPModel Context Protocol是连接大模型和外部工具的标准协议Java 生态里主要靠 Spring AI 和 LangChain4j 做客户端。这个协议在 2024 到 2025 之间做了一次传输层的大改旧版走 HTTP SSE新版走 Streamable HTTP。两套机制的端点路径、HTTP 方法、握手方式都不一样混用就是 404。这篇就围绕 Spring AI 集成 MCP 时 SSE 与 Streamable HTTP 的兼容问题把连接失败、流式响应中断这些坑一个个拆开顺带给出 TaoToken 统一 Key 和 API 通道的可复制配置目标是一次性把 MCP 服务联调跑通。适合谁看正在用 Spring Boot Spring AI 接 MCP 服务端的 Java 开发者被 404、SSE 握手失败、流式响应中途断掉折腾过的同学以及想用 LangChain4j 做纯 Java MCP 客户端、但不确定该选哪种 transport 的人。下面所有配置和命令都可以直接抄改掉你自己的端口和 Key 就能用。2. 协议代沟SSE 和 Streamable HTTP 差在哪2.1 两套传输机制的核心区别先把两版协议的差异摆清楚后面排查才有依据。特性2024-11-05 旧版SSE2025-03-26 新版Streamable HTTP核心协议HTTP SSEStreamable HTTP通信模式双工GET 建 SSE 长连接 POST 发指令单端点统一 POST 交互可选 GET 流式端点数量通常两个/sse 和 /message一个如 /mcp客户端 transportHttpMcpTransportStreamableHttpMcpTransportSpring AI 支持原生支持暂未适配旧版 SSE 的逻辑是客户端先发GET /sse建一个听筒服务端通过这条长连接往下推消息客户端要发指令时再POST到另一个地址常见是/message。两条通道各管一个方向。新版 Streamable HTTP 把双端点砍成一个客户端所有请求都POST /mcp需要流式响应时服务端返回Content-Type: text/event-stream不需要就返回普通 JSON。握手逻辑简化了但和旧版完全不兼容。2.2 404 的本质HTTP Method 不匹配回到那个报错。当你写下McpTransport transport StreamableHttpMcpTransport.builder() .url(http://127.0.0.1:3000/sse) // 错误示范 .build();你的意图是用新版客户端连旧版服务端。新版客户端会向/sse发一个POST请求而旧版服务端的/sse路径只认GET它靠 GET 建长连接。服务端收到一个它不认识的 POST直接返回 404。所以 404 不是路径写错是方法对不上。反过来也一样用旧版HttpMcpTransport去连新版/mcp端点客户端发GET /mcp想建 SSE新版服务端只认 POST同样报错。记住一句话新版客户端连不了旧版服务端旧版客户端也连不了新版服务端这是非此即彼的选择。2.3 Spring AI 与 LangChain4j 的现状Spring AI 目前底层主要基于旧版 LangChain4j 实现遵循 2024-11-05 的 SSE 规范。也就是说在 Spring Boot 项目里配 MCP你得确保服务端支持旧版 SSE 协议强行填 Streamable 的参数是无效的框架底层根本没实现新版握手。LangChain4j 1.0 为了兼容未来引入了StreamableHttpMcpTransport但它不会自动适配所有服务端。选哪个 transport取决于你的服务端跑的是哪版协议而不是你的客户端版本有多新。3. TaoToken 前置统一 Key 与 API 通道MCP 服务联调时模型调用和工具调用往往要分别配 Key来回切换很烦。TaoToken 提供统一的 API 通道把模型对话、编码计划、控制台管理收敛到一个入口MCP 客户端里配置一次就能复用。官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基址不带 UTMhttps://taotoken.net/api几个常用 deep link按需取用模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCodeAnthropichttps://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite提示MCP 服务本身负责工具调度模型推理走 TaoToken 的 API 通道。两者分开配置互不干扰排查问题时也能快速定位是哪一层出的错。4. 可复制配置application.yml 与 config.toml4.1 Spring AI 的 application.ymlSSE 模式Spring AI 走旧版 SSE配置里必须指向服务端的 SSE 入口别填/mcpspring: ai: mcp: clients: my-client: transport: http http: sse-url: http://127.0.0.1:3000/sse # 必须指向 SSE 端点 request-timeout: 30s openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-miniTAOTOKEN_API_KEY从环境变量注入别硬编码进仓库。sse-url是排查重点路径写错或写成/mcp都会 404。4.2 纯 LangChain4j 的 config.tomlStreamable HTTP 模式如果你不用 Spring AI而是纯 LangChain4j 项目且服务端已升级到 2025-03-26 协议用 TOML 管理配置更清爽[mcp] transport streamable-http endpoint http://127.0.0.1:3000/mcp # 新版单端点注意路径变了 timeout_ms 30000 [taotoken] base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model gpt-4o-mini对应的 Java 客户端构建McpTransport transport StreamableHttpMcpTransport.builder() .url(http://127.0.0.1:3000/mcp) // 新版路径 .build();对比一下旧版写法路径和类名都不同McpTransport transport new HttpMcpTransport.Builder() .sseUrl(http://127.0.0.1:3000/sse) // 旧版 SSE 入口 .build();注意/sse和/mcp不是随便换的别名它们对应两套完全不同的握手逻辑。选错一个连接阶段就挂。5. 验证请求curl 检查 SSE 握手与回退配置写完别急着跑 Java先用 curl 把服务端行为摸清楚能省掉大量来回改代码的时间。5.1 验证 SSE 握手旧版curl -N -H Accept: text/event-stream \ http://127.0.0.1:3000/sse-N关闭缓冲方便看流式输出。如果服务端是旧版 SSE你会看到连接保持打开并陆续收到event:和data:行。如果立刻返回 404 或 405说明这个路径不接受 GET服务端可能已经是新版。5.2 验证 Streamable HTTP新版curl -X POST http://127.0.0.1:3000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:initialize,params:{}}新版服务端会返回 JSON 或text/event-stream。如果返回 404说明这个端点不存在服务端大概率还是旧版 SSE。5.3 验证 TaoToken API 通道curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回正常 JSON 就说明 Key 和通道没问题。这一步和 MCP 分开验证能快速判断故障在模型层还是工具层。5.4 成功结果长什么样SSE 模式下curl 会持续输出事件流Java 客户端日志里能看到 transport 建立成功、工具列表拉取完成。Streamable HTTP 模式下POST 返回 200 且 body 是合法 JSON-RPC 响应。两者都通了再跑 Spring AI 的集成测试基本一次过。6. 本篇常见错排查6.1 404 Not Found最常见。先确认服务端协议版本再确认客户端 transport 类型最后核对路径旧版/sse新版/mcp。三者任一不匹配就 404。用第 5 节的 curl 命令能直接定位。6.2 流式响应中途中断SSE 长连接对超时敏感。检查request-timeout是否太短反向代理是否缓冲了text/event-stream。如果中间有网关确认它没把 SSE 当普通响应缓存。Streamable HTTP 模式下确认Accept头同时包含application/json和text/event-stream。6.3 连接建立但工具列表为空transport 通了不代表业务通。检查 MCP 服务端是否正确注册了工具以及客户端初始化时是否发了initialize和tools/list。日志级别调到 DEBUG看 JSON-RPC 往返内容。6.4 混用 transport 导致握手失败有人想兼容两种同时配 SSE 和 Streamable。不行这是非此即彼的选择。服务端是旧版就用HttpMcpTransport新版就用StreamableHttpMcpTransport别在一个客户端里塞两套。6.5 Key 或通道报 401模型层报 401检查TAOTOKEN_API_KEY是否注入成功、base-url是否写成https://taotoken.net/api。MCP 层报鉴权错检查服务端自己的 token 配置和 TaoToken 的 Key 是两回事。7. 继续联调按场景选对入口排障和接入相关的直接看 API Keys 和接入文档把 Key 和通道先固定下来API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite想先验证模型通不通用模型对话页面发一条消息最快模型对话https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite如果你在做长期编码或 Agent 类项目MCP 工具调用会反复跑建议直接上 Coding Plan省得每次手动配Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite我自己的习惯是先用 curl 把 SSE 和 Streamable HTTP 两条路都探一遍确认服务端到底跑哪版再回头改 Spring AI 的sse-url或 LangChain4j 的endpoint。这一步花五分钟能省掉半小时对着 404 猜。协议过渡期就是这样新旧并存选对 transport 比升级依赖更重要。
阅读完成 · 觉得有帮助？
