1. 从 Spring Boot 配置说起MCP 服务器启动器到底解决什么问题如果你正在用 Spring AI 做 AI 应用大概率会遇到一个绕不开的环节模型需要调用外部工具、读取资源、复用提示词模板而这些能力怎么以标准协议暴露出去Model Context Protocol简称 MCP就是干这个的。它把「模型 ↔ 工具/资源/提示词」之间的交互抽象成一套协议而 Spring AI 提供的 MCP 服务器启动器让你在 Spring Boot 项目里几乎零成本地把这些能力挂上去。我先把结论放前面MCP 服务器启动器本质上是一个「自动配置 传输层适配」的组合包。你引入不同的 starter它就帮你决定用 STDIO、SSE over WebMVC 还是 SSE over WebFlux 来通信你写几个Tool注解的方法或者注册几个 Bean它就自动把这些注册成 MCP 的 tools、resources、prompts。对使用 Spring Boot 接入 Model Context Protocol 的开发者来说省掉的是手写协议解析、连接管理、事件通知这些脏活。它适合谁三类人最直接受益。第一类是做本地命令行工具或桌面应用的用 STDIO 传输进程内通信轻量无 Web 依赖。第二类是做传统 Web 应用的用 WebMVC 的 SSE 长连接默认路径/sse跟现有 Spring MVC 项目无缝融合。第三类是做云原生、高并发场景的用 WebFlux 的响应式 SSE非阻塞模型扛得住大量并发连接。但真正落地时很多人卡在同一个地方文档看懂了配置却写不对。尤其是当你要把 MCP 服务器的 endpoint 和鉴权指向一个统一的模型网关时application.yml里那几个属性到底怎么填、填完怎么验证通道是通的文档往往一笔带过。这篇就按「原问题 → 前置准备 → 可复制配置 → 验证请求 → 排错 → 后续」的顺序把 Spring AI MCP 服务器启动器的配置改到 TaoToken 的完整过程走一遍每一步都给可复制的片段。先说清楚一个容易混淆的点MCP 服务器启动器负责的是「把工具暴露给模型客户端」而模型本身的调用比如让模型决定调用哪个工具走的是另一条链路。这两条链路可以指向不同的服务。本文聚焦的是把 MCP 服务器相关的 endpoint 与鉴权配置统一到 TaoToken让工具调用通道和模型通道在同一个网关下管理减少多套 Key、多套地址的维护成本。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套在动application.yml之前得先把 TaoToken 这边的三件套准备好。不管你后面用哪种 starter这三样东西都是配置的核心Base URL、API Key、Model ID。少一个都跑不通而且报错信息往往不会直接告诉你缺了哪个。Base URL 用https://taotoken.net/api注意这里不带任何查询参数就是干净的 API 根路径。API Key 需要你去控制台生成路径是 API Keys 页面生成后复制保存它只显示一次。Model ID 则取决于你要调用的具体模型在模型列表里能看到对应的标识符。我建议你按这个顺序操作避免来回切页面第一步打开控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentspring_ai_mcp_starterutm_campaignrewrite登录后进入 API Keys 管理。第二步新建一个 Key命名建议带上用途比如spring-ai-mcp-dev方便以后区分环境。第三步把生成的 Key 立刻存到本地环境变量或密码管理器里别直接硬编码进代码仓库。关于 Key 的存放我踩过的坑是早期图省事直接写在application.yml里提交了后来换 Key 时到处找。现在我的做法是用环境变量占位配置文件里写${TAOTOKEN_API_KEY}本地用.env或者 IDE 的运行配置注入生产环境用密钥管理服务。这样配置文件可以放心进版本库。Model ID 这块要提醒一句不同模型的 ID 不一样别凭记忆填。去模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentspring_ai_mcp_starterutm_campaignrewrite实际发一条消息确认模型可用同时记下你选的模型标识。这一步看起来多余但能帮你排除「Key 没问题但模型 ID 写错」这类低级错误。如果你后面打算长期跑编码类或 Agent 类任务可以考虑 Coding Plan它在持续调用场景下更省心具体在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentspring_ai_mcp_starterutm_campaignrewrite能看到说明。不过本文的验证流程用按量 Key 就够了先把通道跑通再说。三件套准备好之后还要确认你的 Spring Boot 项目版本和 Spring AI 版本匹配。MCP 服务器启动器对 Spring AI 的版本有要求版本错配会出现 Bean 找不到或者自动配置不生效的问题。建议在pom.xml里显式锁定 Spring AI 的 BOM 版本别让 Maven 自己解析。3. 可复制配置application.yml 与启动器依赖片段这一节是全文的核心直接给可复制的片段。我按「依赖 → 配置 → 工具注册」三层来写你可以整段抄也可以按需裁剪。先看依赖。根据你选的传输方式三选一即可别同时引入多个 starter否则自动配置会打架。STDIO 版本适合本地进程内通信dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server/artifactId /dependencyWebMVC 版本适合传统 Web 应用基于 SSEdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependencyWebFlux 版本适合响应式、高并发场景dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webflux/artifactId /dependency接下来是application.yml。这里的关键是把 MCP 服务器的 endpoint 和鉴权相关配置统一到 TaoToken 的地址体系下。注意配置前缀是spring.ai.mcp.server别写错层级spring: ai: mcp: server: enabled: true name: taotoken-mcp-server version: 1.0.0 type: ASYNC sse-message-endpoint: /mcp/messages base-url: /api/v1 tool-change-notification: true resource-change-notification: true # 模型通道指向 TaoToken openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: ${TAOTOKEN_MODEL_ID}这段配置里有两个地址概念要分清。spring.ai.mcp.server.base-url是你自己 MCP 服务器的 URL 前缀比如设成/api/v1那 SSE 端点就变成/api/v1/sse消息端点变成/api/v1/mcp/messages。而spring.ai.openai.base-url是模型调用的上游地址指向 TaoToken 的 API 根路径。两者不要混。如果你用的是 WebFlux 且需要更细的传输控制可以加上spring: ai: mcp: server: stdio: false sse-message-endpoint: /mcp/messagesstdio: false表示不启用 STDIO 传输走 SSE。这个属性默认就是 false但显式写出来能避免歧义。工具注册部分用Tool注解最省事。写一个 Service方法上加注解再通过ToolCallbackProvider暴露出去Service public class CalculatorService { Tool(description 执行两个数字的加法运算) public int add(int a, int b) { return a b; } Tool(description 执行两个数字的乘法运算) public int multiply(int a, int b) { return a * b; } }然后在配置类里注册Configuration public class McpToolConfig { Bean public ToolCallbackProvider calculatorTools(CalculatorService service) { return MethodToolCallbackProvider.builder() .toolObjects(service) .build(); } }到这里配置和代码都齐了。启动应用如果日志里出现 MCP 服务器初始化的相关信息说明自动配置生效了。接下来就是验证通道。4. 验证请求一次 MCP 工具调用确认通道连通与返回结构配置写完不验证等于没配。这一节用一个最小的 MCP 工具调用确认通道连通、鉴权生效、返回结构符合预期。先启动 Spring Boot 应用。如果你用的是 WebMVC 或 WebFlux 的 SSE 传输启动后访问 SSE 端点确认服务在监听。默认路径是/sse如果配了base-url: /api/v1那就是/api/v1/sse。用 curl 快速探一下curl -N http://localhost:8080/api/v1/sse-N表示禁用缓冲SSE 是长连接你会看到连接保持打开并持续接收事件。如果立刻断开或者返回 404说明端点路径不对回去检查base-url和sse-message-endpoint的拼接结果。接下来用 MCP 客户端发起一次工具调用。Python 客户端示例from mcp.client import McpClient client McpClient(sse_urlhttp://localhost:8080/api/v1/sse) response client.send_tool_request( add, {a: 5, b: 3} ) print(response.result)预期输出是8。如果拿到这个结果说明整条链路是通的客户端连上 SSE → 服务器识别工具名add→ 调用CalculatorService.add→ 返回结果。但这里有个细节容易被忽略工具名。Tool注解的方法名默认就是工具名但如果你在注解里指定了name属性客户端要用指定的名字。我建议在注解里显式写name避免重构方法名时把客户端调用打断。再验证一下模型通道是否指向了 TaoToken。发一个简单的对话请求看返回是否正常curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: ${TAOTOKEN_MODEL_ID}, messages: [{role: user, content: ping}] }返回里如果有正常的choices结构说明 Key 和 Model ID 都对。这一步和 MCP 工具调用是两条独立链路但都指向同一个网关方便统一管理。验证通过后建议把这次调用的请求和响应结构记下来尤其是choices数组里的字段。后面如果出现reading choices相关报错对照这个正常结构就能快速定位是上游返回格式变了还是解析代码有问题。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错我按出现频率排一下每个都给排查路径。第一类401 Unauthorized。这个最直接就是鉴权没过。先确认TAOTOKEN_API_KEY环境变量真的注入了别只在 IDE 里配了但命令行启动时没带上。用echo $TAOTOKEN_API_KEY确认非空。然后确认请求头格式是Authorization: Bearer keyBearer 后面有一个空格这个空格漏了也会 401。如果 Key 是从控制台复制的注意别把首尾空格带进去。第二类local proxy failed。这个报错通常出现在客户端尝试连接本地代理或转发时。排查方向是确认你的 SSE 地址写的是实际服务地址而不是某个中间层地址。如果你在application.yml里配了base-url客户端拼接时要用完整路径。另外检查端口是否被占用8080 被占时应用可能起在别的端口客户端却还在连 8080。第三类reading choices 相关报错。这类通常出现在解析模型返回时choices字段读不到或者结构不符。先确认上游返回的 JSON 里确实有choices数组用上一节的 curl 命令直接看原始返回。如果返回正常但代码报错检查你的反序列化模型类字段名是否和返回一致大小写敏感。还有一种情况是返回了错误对象而不是正常结构比如额度不足或模型不存在这时choices自然不存在要先看返回里的error字段。第四类OAuth 相关报错。如果你在 MCP 服务器上叠加了 Spring Security 做认证SSE 端点可能要求 OAuth token。排查时先确认安全配置有没有把/sse和/mcp/messages路径放行或者客户端有没有带上正确的 token。开发阶段可以先临时放行这两个路径确认通道本身没问题再逐步加回安全策略。这里补一个三件套的检查清单出现任何连接类问题都先过一遍Base URL 是否为https://taotoken.net/api不带多余路径、API Key 是否有效且未过期、Model ID 是否与模型列表一致。这三样任意一个错都会表现为连接失败或鉴权失败但报错信息可能五花八门。如果你用的是 Claude Code 或类似的编码工具接入配置项名称可能不同但本质还是 Base URL、Key、Model ID 三件套。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentspring_ai_mcp_starterutm_campaignrewrite有更细的说明遇到工具特有的配置项可以去对照。6. 把配置沉淀下来从验证通过到长期可用通道验证通过只是第一步真正省心的是把配置沉淀成可复用的形式。我的做法是把application.yml里的环境相关部分全部抽成变量本地、测试、生产各一套 profile配置文件本身保持干净。具体来说spring.ai.openai.base-url和api-key这两项在不同环境可能不同用${TAOTOKEN_BASE_URL}和${TAOTOKEN_API_KEY}占位。本地开发用.env文件配合 IDE 插件注入CI 环境用流水线变量生产用密钥管理。这样同一份配置文件能在所有环境跑不会出现「本地能跑线上挂」的经典问题。工具注册这块随着工具数量增长建议按业务域拆成多个ToolCallbackProviderBean而不是全塞在一个类里。每个 Provider 负责一组相关工具命名清晰排查时能快速定位是哪个域的工具出了问题。同时给每个工具写清楚description模型选择工具时依赖这个描述写得含糊会导致模型选错工具。监控方面tool-change-notification和resource-change-notification建议保持开启。工具或资源发生变更时客户端能收到通知并刷新避免用到过期的工具定义。如果你有自定义的日志或拦截需求可以实现McpServerCustomizer来扩展比如记录每次工具调用的入参和耗时这对排查线上问题很有帮助。最后说一个实际经验MCP 服务器的配置改动最好配合一次完整的端到端验证再上线。改动base-url或sse-message-endpoint这类路径相关配置时客户端侧的连接地址也要同步改两边不一致是最隐蔽的坑。把验证脚本固化下来每次改配置跑一遍比事后排查省事得多。如果你还没生成 API Key现在可以去https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentspring_ai_mcp_starterutm_campaignrewrite创建然后按本文的配置片段把 MCP 服务器启动器接上跑一次工具调用验证。通道通了之后剩下的就是往里面加工具、加资源逐步把能力补齐。
