1. Spring Boot 里把 MCP Server 跑起来Key 却散落在三个文件里如果你正在用 Spring Boot 写 Java 后端又想给 AI 应用暴露一批工具Tools、资源Resources和提示Prompts那 Spring AI 的 MCP Server Boot Starters 基本是绕不开的。它做的事情很直白把 Model Context Protocol 服务端的组件用 Spring Boot 自动配置的方式装配好你只要加依赖、写注解、配几行 yml一个能对外提供能力的 MCP Server 就起来了。适合谁适合那些手里已经有一堆 Spring 服务、想让 AI 客户端比如 Claude Code、各类 Agent 框架通过标准协议调用这些能力的后端同学。但真正落地时麻烦往往不在 MCP 本身而在“模型接入”这一层。MCP Server 负责暴露能力可它背后要调用的模型、要切换的供应商、要管理的密钥经常散落在application.yml、config.toml、settings.json好几个地方。多模型切换时改一处漏一处本地能跑、换个环境就 401。我试过把 Key 硬编码进配置结果提交前忘了删差点出事。这篇就聚焦一个目标用 TaoToken 做统一 Key 入口把 Spring AI MCP Server Boot Starters 的配置骨架一次性搭好让你在多个模型之间切换时只改一个地方。下面从依赖、yml、config.toml、settings.json 到启动验证一步步给可复制的片段。2. TaoToken 前置统一 Key 与接入地址TaoToken 在这里扮演的角色是“统一入口”。你不需要为每个模型供应商单独维护一套 Key 和 Base URL而是拿一个 TaoToken 的 Key通过它的 API 地址去访问不同模型。对 Spring AI 来说这意味着一件事把base-url和api-key指向 TaoToken模型名按需切换即可。需要提前准备的东西不多一个 TaoToken 账号登录后在控制台创建 API Key。控制台地址https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite记下 API 基础地址https://taotoken.net/api 这个地址不加 UTM直接用于配置想好你要接的模型名比如对话模型、编码模型后面在 yml 里作为model值填进去创建 Key 的入口在 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。拿到形如sk-xxxx的字符串后先别急着写进代码放到环境变量里更稳妥后面配置里用${TAOTOKEN_API_KEY}引用。注意Key 属于敏感信息不要直接提交到 Git。本地用环境变量CI/CD 用密钥管理这是基本习惯。如果你还没决定用哪个模型可以先在模型对话页面手动试一下确认 Key 和模型名都对得上https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。确认通了再回到 Spring Boot 里配能省掉很多“到底是 Key 错还是代码错”的排查时间。3. 可复制配置依赖、application.yml、config.toml、settings.json3.1 Maven 依赖选对 StarterMCP Server Boot Starters 按传输方式分了好几种。Web 场景下现在推荐用 Streamable-HTTPSSE 从 2.0.0 起已弃用。下面以 WebMVC Streamable 为例pom.xml里加dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency第一个是 MCP Server 的 WebMVC 启动器第二个是模型接入用的 OpenAI 兼容 Starter——TaoToken 的 API 是 OpenAI 兼容格式所以用它来接最省事。版本号跟着你项目的 Spring AI BOM 走别自己乱填。3.2 application.ymlMCP Server 与模型接入骨架这是核心配置。MCP Server 部分用STREAMABLE协议模型部分把base-url指向 TaoTokenserver: port: 8080 spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 mcp: server: protocol: STREAMABLE type: SYNC annotation-scanner: enabled: true capabilities: tool: true resource: true prompt: true几个关键点解释一下。protocol: STREAMABLE对应 Streamable-HTTP 传输服务端作为独立进程用 HTTP POST/GET 处理多客户端连接必要时用 SSE 流式返回。type: SYNC表示用McpSyncServer只注册同步的注解方法如果你写的是响应式方法就改成ASYNC它会用McpAsyncServer并带上 Project Reactor 支持。annotation-scanner.enabled: true让自动配置去扫描带 MCP 注解的 Bean。capabilities里三项默认都是启用的写出来是为了让你知道可以按需关。关掉某项服务端就不会向客户端注册对应能力。3.3 config.toml客户端侧连接 MCP Server如果你用的是支持 MCP 的客户端比如 Claude Code 这类它通常读一个config.toml或类似配置文件来知道去哪连 MCP Server。Streamable-HTTP 的写法大致如下[[mcp_servers]] name spring-boot-mcp transport streamable-http url http://localhost:8080/mcp这里的url路径取决于你的传输提供者注册的端点WebMVC Streamable 默认挂在/mcp下。启动 Spring Boot 后客户端就能通过这个地址发现你暴露的 Tools 和 Resources。3.4 settings.jsonTaoToken 统一 Key 片段有些工具链比如某些 Agent 框架或编辑器插件用settings.json管理模型凭证。把 TaoToken 的 Key 和地址写进去格式类似{ model_providers: { taotoken: { base_url: https://taotoken.net/api, api_key: ${TAOTOKEN_API_KEY}, models: [gpt-4o-mini, claude-3-5-sonnet] } } }这样无论上层是 Spring AI 还是别的客户端Key 都从同一个环境变量取切换模型只改models列表里的名字不用动 Key。4. 验证请求写一个 Tool启动后调一次配置写完得验证它真的通了。分两步先写一个带McpTool的 Bean再启动应用发一个请求。4.1 写一个可被扫描的 ToolComponent public class CalculatorTools { McpTool(name add, description 将两个数字相加) public int add( McpToolParam(description 第一个数字, required true) int a, McpToolParam(description 第二个数字, required true) int b) { return a b; } McpResource(uri config://{key}, name 配置) public String getConfig(String key) { return value-of- key; } }McpTool会把方法标记成 MCP 工具并自动生成 JSON SchemaMcpResource通过 URI 模板暴露资源。自动配置会扫描这些 Bean创建对应规范并注册到 MCP Server。4.2 启动并验证启动类保持最简SpringBootApplication public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } }启动后用 curl 走一次 Streamable-HTTP 的初始化请求确认服务端在监听curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }如果返回里带serverInfo和capabilities说明 MCP Server 起来了。接着调工具curl -X POST http://localhost:8080/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: {name: add, arguments: {a: 3, b: 4}} }预期返回里result.content包含7。到这一步Spring AI 与 MCP 通道就算跑通了。模型侧是否通可以在业务代码里注入ChatClient发一句测试确认 TaoToken 的 Key 生效。5. 本篇常见错排查配置跑不通八成是下面几个原因。按顺序查能省不少时间。启动报找不到 MCP 端点。检查spring.ai.mcp.server.protocol是否写成了STREAMABLE以及依赖是不是spring-ai-starter-mcp-server-webmvc。如果用了 WebFlux 却引了 WebMVC 的 starter传输提供者不会注册端点自然不存在。Tool 没被注册。先确认annotation-scanner.enabled: true再确认type和方法的同步/异步属性匹配。SYNC只注册同步方法ASYNC只注册异步方法写反了方法会被静默忽略不报错很容易误判。调用模型返回 401。大概率是api-key没读到环境变量。检查${TAOTOKEN_API_KEY}是否真的在运行环境里设置了别只在 IDE 的 Run Configuration 里设、换到命令行就没了。另外确认base-url是https://taotoken.net/api结尾不要多加/v1之类的路径OpenAI 兼容 Starter 会自己拼。Streamable 请求返回 406。多半是Accept头没带text/event-stream。Streamable-HTTP 允许用 SSE 流式返回多条消息客户端要显式声明接受这种类型否则服务端可能拒绝。多模型切换后行为不对。检查model值是否在 TaoToken 支持的模型列表里。名字写错时有的供应商返回 404有的返回一个默认模型表现不一致最好先在模型对话页面确认模型名可用。提示排障时把日志级别调到 DEBUGlogging.level.org.springframework.aiDEBUG能看到 MCP 注册和模型请求的细节比盲猜快得多。6. 把 Key 收口到一处后面切换才不痛整套配置下来最值得坚持的一点是Key 只从环境变量取模型名只在一处改。Spring AI 的 MCP Server Boot Starters 负责把能力暴露出去TaoToken 负责把模型接入收口两者职责分开配置就不会互相污染。如果你后面要长期跑编码类任务或 Agent建议直接看 Coding Plan它更适合持续性的编码场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。接入细节和参数说明都在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。Claude Code 相关的接入方式可以看https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后留一个我踩过的坑config.toml里的 MCP Server 地址别写127.0.0.1又指望容器里的客户端能连上跨容器时用服务名或宿主机地址。这种问题不报配置错只表现为连接超时查起来最费劲。