1. 为什么 Spring AI 项目里 MCP 服务器总接不通Spring AI 的 MCPModel Context Protocol服务器接入是这两年在 Java 生态里被问得最多的一类问题。它本质上解决的是「让大模型能调用你本地或远端工具」这件事模型负责理解意图MCP 服务器负责把工具、资源、提示词以标准协议暴露出去客户端再把这些能力挂到对话链路上。听起来很顺但真到落地很多人卡在第一步——传输模式选错、依赖引错、配置项写错启动日志里一堆transport相关报错接口却始终返回空。我见过最典型的场景是这样的一个 Spring Boot 项目里同时引了spring-ai-starter-mcp-server-webmvc和spring-ai-starter-mcp-server-webflux本地跑起来看着没事一调工具就发现 SSE 端点连不上还有人把 STDIO 服务器当成 HTTP 服务去访问结果自然是 connection refused。更隐蔽的是模型调用链路——MCP 服务器本身通了但模型侧没有统一入口Key 散落在各个配置文件里换一个模型就要改一遍代码。这篇笔记就聚焦两件事STDIO 与 SSE 两类 MCP 服务器在 Spring AI 里到底怎么配、怎么验证以及如何用 TaoToken 的统一 Key/API 通道把模型调用链路收拢成一条。目标很明确——一次跑通两种传输模式的 MCP 服务对接配置片段可以直接复制。先说清楚适用人群如果你正在用 Spring AI 做 Agent、工具调用、RAG 之外的上下文扩展或者你手里有一堆 Python/Node 写的 MCP 工具想接进 Java 服务这篇就是给你写的。不需要你之前用过 MCP但需要你会基本的 Spring Boot 配置和 Maven 依赖管理。STDIO 和 SSE 的区别用一句话概括STDIO 是「进程内管道」客户端启动服务器进程通过标准输入输出通信适合命令行工具和桌面场景SSE 是「HTTP 长连接」服务器作为 Web 服务暴露端点客户端通过 Server-Sent Events 接收消息适合多客户端、跨网络的场景。选错模式后面所有配置都是白费。2. TaoToken 统一通道的前置准备与依赖选型在动手配 MCP 之前先把模型调用这条链路理清楚。Spring AI 本身支持多种模型提供商但如果你项目里同时用 OpenAI 兼容接口、Anthropic、或者其他模型每个都要单独配 Key、单独写 base-url维护成本很高。TaoToken 在这里的角色是一个统一的 API 通道你只需要一个 Key、一个 Base URL就能在 Spring AI 里切换不同模型MCP 服务器暴露的工具也能挂到同一条链路上。前置准备分三步。第一步拿到 Key。访问https://taotoken.net/api-keys带 utm 参数?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_stdio_sseutm_campaignrewrite创建 API Key复制保存。第二步确认 Base URL 是https://taotoken.net/api注意这个地址不加任何 UTM 参数直接用于代码里的base-url配置。第三步想清楚你要接的模型 ID比如gpt-4o、claude-3-5-sonnet这类后面配置里会用到。依赖选型是这一步最容易踩坑的地方。Spring AI 的 MCP 服务器 starter 有三个Starter传输方式适用场景关键依赖spring-ai-starter-mcp-serverSTDIO命令行、桌面工具、无 Web 依赖无额外 Web 依赖spring-ai-starter-mcp-server-webmvcSSESpring MVC传统 Servlet 项目spring-boot-starter-webspring-ai-starter-mcp-server-webfluxSSESpring WebFlux响应式项目spring-boot-starter-webflux这里有个官方文档里明确提醒过的坑如果你的类路径里同时存在DispatcherServlet和DispatcherHandlerSpring Boot 会优先用DispatcherServlet。也就是说你项目里如果已经引了spring-boot-starter-web就别再用webflux那个 starter否则 SSE 端点行为会和你预期不一致。我实测下来最稳的做法是Servlet 项目用webmvc纯响应式项目用webflux别混。Maven 依赖片段以 WebMVC 为例dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency如果你要同时支持 STDIO 和 SSE可以在 WebMVC starter 基础上通过spring.ai.mcp.server.stdiotrue开启 STDIO 传输。这样同一个服务器既能被命令行客户端以 STDIO 方式拉起也能通过 HTTP SSE 端点访问。注意这个开关默认是关的不开的话 STDIO 客户端连不上。模型侧依赖如果你用 OpenAI 兼容协议接 TaoToken加dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency到这里依赖和 Key 都齐了。下一步进入配置环节这也是全文最核心的部分。3. 可复制的 application.yml 与 MCP 客户端配置配置分两块MCP 服务器自身的配置以及模型调用链路TaoToken的配置。先给一份完整的application.yml你可以直接复制改。server: port: 8080 spring: ai: # TaoToken 统一模型通道 openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o temperature: 0.7 # MCP 服务器配置 mcp: server: name: spring-ai-mcp-server version: 1.0.0 type: SYNC instructions: This server provides weather and system info tools capabilities: tool: true resource: true prompt: true completion: true # SSE 相关 sse-message-endpoint: /mcp/messages keep-alive-interval: 30s # 同时开启 STDIO 传输 stdio: true几个关键点解释一下。base-url必须是https://taotoken.net/api不要带任何查询参数api-key用环境变量注入别硬编码在文件里。type: SYNC表示同步服务器如果你用 WebFlux 响应式可以改成ASYNC。sse-message-endpoint是 SSE 的消息端点路径客户端会往这个路径发消息。keep-alive-interval是保活间隔默认关闭设成30s后服务器会定期给客户端发 ping防止长连接被中间层断开。如果你只想跑 STDIO不需要 SSE那配置可以简化成spring: ai: mcp: server: name: stdio-mcp-server version: 1.0.0 type: SYNC对应的依赖换成spring-ai-starter-mcp-server不需要 Web 依赖。接下来是 MCP 客户端配置。Spring AI 的 MCP 客户端 starter 是spring-ai-starter-mcp-client配置方式有两种STDIO 客户端和 SSE 客户端。STDIO 客户端配置spring: ai: mcp: client: stdio: connections: weather-server: command: java args: - -jar - /path/to/your-mcp-server.jarSSE 客户端配置spring: ai: mcp: client: sse: connections: weather-server: url: http://localhost:8080 sse-endpoint: /sse注意sse-endpoint默认是/sse如果你服务器端改了路径这里要对应改。客户端连接名weather-server可以自定义后面在代码里通过这个名字拿工具。模型调用侧如果你想在代码里显式指定 TaoToken 通道可以这样写Bean public ChatClient chatClient(OpenAiChatModel chatModel) { return ChatClient.builder(chatModel) .defaultSystem(You are a helpful assistant with access to MCP tools.) .build(); }OpenAiChatModel会自动读取spring.ai.openai下的配置也就是我们上面写的 TaoToken 地址和 Key。这样模型调用和 MCP 工具调用就走同一条链路了。这里补一句关于 Claude Code 的配置如果你同时用 Claude Code 做开发它的settings.json里也可以配 TaoToken{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: your-token-here } }三件套记牢Base URL 是https://taotoken.net/apiKey 从https://taotoken.net/api-keys拿Model ID 按你实际用的填。这三样对齐了模型侧就不会出问题。4. 启动验证日志、SSE 端点与工具调用实测配置写完启动项目重点看三处启动日志、SSE 端点、工具调用返回。启动日志里你应该能看到类似这样的输出Registered MCP tool: getWeather MCP server started with name: spring-ai-mcp-server SSE endpoint available at: /sse STDIO transport enabled如果没看到Registered MCP tool说明你的ToolCallbackProviderBean 没被扫描到检查一下Bean方法是否在SpringBootApplication扫描范围内。如果没看到SSE endpoint available检查依赖是不是引成了纯 STDIO 的 starter。SSE 端点验证用 curl 直接连curl -N http://localhost:8080/sse正常的话会保持连接并输出事件流类似event: endpoint data: /mcp/messages?sessionIdxxx这个sessionId是后续发消息要用的。如果你看到 404检查sse-message-endpoint配置和实际请求路径是否一致。如果连接立刻断开看日志里有没有keep-alive相关报错。工具调用验证写一个简单的 ControllerRestController public class McpTestController { private final ChatClient chatClient; public McpTestController(ChatClient chatClient) { this.chatClient chatClient; } GetMapping(/test-tool) public String testTool(RequestParam String city) { return chatClient.prompt() .user(Whats the weather in city ?) .call() .content(); } }启动后访问http://localhost:8080/test-tool?cityBeijing如果返回里包含天气信息说明模型成功调用了 MCP 工具。如果返回的是「I dont have access to weather data」说明工具没挂上检查 MCP 客户端连接配置。STDIO 模式的验证稍微不同。你需要用 MCP 客户端以 STDIO 方式拉起服务器进程比如用官方的 MCP Inspector 工具或者自己写一个简单的 STDIO 客户端。日志里会显示STDIO transport initialized然后你通过标准输入发 JSON-RPC 请求标准输出会返回结果。实测下来最容易出问题的是模型侧和 MCP 侧的 Key 混用。有人把 TaoToken 的 Key 配到了 MCP 服务器配置里或者反过来结果两边都报 401。记住TaoToken 的 Key 只用于模型调用MCP 服务器本身不需要 Key除非你开了安全认证。5. 常见报错排查401、local proxy failed 与 choices 解析这一节列几个真实遇到过的报错对照着排查。401 Unauthorized。这个最常见两种可能一是 TaoToken Key 没配或配错检查spring.ai.openai.api-key是否读到了环境变量二是 Key 过期或被禁用去https://taotoken.net/api-keys确认状态。如果日志里出现401且伴随invalid_api_key基本就是 Key 问题。local proxy failed / connection refused。这个通常出现在 SSE 客户端连服务器时。检查三点服务器是否真的启动了看端口监听、url配置是否带了http://前缀、sse-endpoint路径是否和服务器端一致。如果是 STDIO 模式报这个检查command和args是否能正确拉起进程路径别写相对路径。Error reading choices / choices is null。这是模型返回解析失败多半是 TaoToken 通道返回的格式和 Spring AI 预期不一致。检查base-url是不是写成了https://taotoken.net/api/末尾多了斜杠或者模型 ID 写错了。还有一种情况是你用的模型不支持 chat completions 格式换一个模型试试。OAuth / authentication failed。如果你在 MCP 客户端配置里开了 OAuth但服务器端没配对应的认证就会报这个。MCP 服务器的安全认证是可选的初期调试建议先关掉跑通再说。No tool callbacks registered。工具没注册上。检查你的ToolCallbackProviderBean 是否返回了非空列表以及Tool注解的方法是否是 public 的。Spring AI 只会扫描 public 方法。SSE connection closed unexpectedly。长连接被断开多半是keep-alive-interval没设或者中间有反向代理超时。设成30s试试如果还不行检查代理层的 read timeout。排查顺序建议先看启动日志有没有报错再用 curl 测 SSE 端点最后测工具调用。一层层往下别跳步。6. 把两种传输模式收进同一条链路STDIO 和 SSE 不是二选一的关系。实际项目里我更推荐的做法是用 WebMVC starter 起一个 SSE 服务器同时开stdio: true这样命令行工具和 Web 客户端都能接。模型侧统一走 TaoToken 通道Key 和 Base URL 只维护一份。如果你要长期跑 Agent 类任务建议把 Coding Plan 也用上https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_stdio_sseutm_campaignrewrite它适合需要持续调用模型、频繁触发工具的场景比按次调用更划算。模型对话调试可以用https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_stdio_sseutm_campaignrewrite快速验证通道是否正常。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentmcp_stdio_sseutm_campaignrewrite遇到配置项不确定的时候翻一下。最后留一个我踩过的坑别在application.yml里同时配spring.ai.mcp.server.stdiotrue和spring.ai.mcp.client.stdio前者是服务器开 STDIO 传输后者是客户端连 STDIO 服务器两个概念配混了会互相干扰。服务器和客户端分开配各管各的。