SpringAI系列 - MCP篇（三） - 用 TaoToken 统一 Key 打通 MCP Server Boot Starter 鉴权链路

1. 为什么 MCP Server Boot Starter 的鉴权总在联调时翻车SpringAI 的 MCP Server Boot Starter 把工具、资源、提示词三件套都封装好了spring-ai-starter-mcp-server-webmvc一引入/sse和/mcp/messages端点自动就位本地起服务、写个Tool方法MCP Client 连上来就能调。这套流程在纯本地、纯工具调用的场景下确实顺滑但一旦 MCP Server 内部需要调用外部模型服务——比如工具方法里要跑一次大模型推理、资源生成要调模型补全、或者 Sampling 能力要回落到真实模型——鉴权链路立刻变成最烦人的一环。问题出在哪MCP Server 本身是个工具提供方它对外暴露的是 MCP 协议端点但它内部如果要访问模型 API就得自己维护一套 base-url 和 api-key。很多同学在本地开发时习惯把 key 硬编码在application.yml里或者每个工具类各写一份RestClient配置结果就是换一个模型供应商要改五六个文件联调时 key 过期了不知道是哪个环节报的 401团队里每个人的 key 还不一样提交代码时又怕把 key 带上去。更麻烦的是MCP Server 的 Sampling 能力Server 反向请求 Client 的模型和 Server 内部直接调模型这两条路径的鉴权配置经常被混在一起排查起来像拆毛线团。我试过在一个 webmvc 的 MCP Server 里同时接三个模型供应商每个工具方法里各写一套WebClient结果光是 base-url 就写错了两次一次是漏了/v1一次是把 SSE 端点的路径当成了 API 路径。后来统一收敛到一个 Key 通道所有模型调用都走同一个 base-url 和 api-key配置文件从四十多行缩到八行联调时只需要确认一个环境变量。这篇就按这个思路把 SpringAI MCP Server Boot Starter 接入外部模型服务时的鉴权配置讲清楚给出application.yml里base-url和api-key的可复制片段再演示启动后通过/mcp端点发起一次工具调用、确认请求经统一 Key 通道正常返回的完整动作。适合谁看正在用 SpringAI 1.0.0-M8 或相近版本做 MCP Server 本地开发的同学工具方法里需要调外部模型、但被鉴权配置绕晕的同学想把 MCP Server 的模型调用链路统一到一个 Key 上、方便联调和交接的同学。核心检索词就三个SpringAI、MCP Server Boot Starter、统一 Key 鉴权链路。下面从原问题场景开始一步步把配置和验证做出来。2. TaoToken 在 MCP Server 鉴权链路里的位置与准备先把 TaoToken 在这个链路里的角色说清楚。MCP Server Boot Starter 本身不负责模型鉴权它只负责 MCP 协议端点的暴露和工具/资源/提示词的注册。当你的工具方法内部需要调用大模型时这个调用是普通的 HTTP 请求需要一个 base-url 和一个 api-key。TaoToken 在这里扮演的就是统一模型服务入口你拿到一个 API Key配一个 base-url所有模型调用都走这个通道不用为每个供应商单独维护一套凭证。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意这两个地址的区别官网带 UTM 参数用于来源归因API 基址不带 UTM配置到application.yml里的应该是 API 基址。这一点在联调时特别容易搞混有人把带 UTM 的完整 URL 填进base-url结果请求路径变成https://taotoken.net/?utm_source.../v1/chat/completions直接 404。准备动作分三步。第一步在 TaoToken 控制台创建一个 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后复制出来形如sk-开头的一串字符。这个 Key 就是后面application.yml里api-key的值。第二步确认你要用的模型 ID比如claude-sonnet-4-20250514或gpt-4o这类模型 ID 会作为请求体里的model字段。第三步确认你的 SpringAI 版本和 MCP Server Starter 的依赖已经引入spring-ai-starter-mcp-server-webmvc在pom.xml里spring-ai-bom的版本是1.0.0-M8或你实际使用的版本。这里有个容易忽略的点MCP Server 的spring.ai.mcp.server.base-url和模型服务的base-url是两个完全不同的东西。前者是 MCP Server 自身对外暴露端点的路径前缀默认空后者是模型 API 的基址。很多同学在application.yml里看到base-url就以为是模型地址结果配错了位置。下面配置片段里我会把两者分开写用注释标清楚。注意API Key 不要硬编码在提交到 Git 的配置文件里。本地开发可以用环境变量占位比如${TAOTOKEN_API_KEY}然后在 IDE 的运行配置或 shell 里 export。这样既方便联调又不会把 key 带进版本库。另外如果你用的是 Claude Code 或类似的编码工具做辅助开发TaoToken 也提供了对应的接入方式模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这些在排查鉴权问题时都会用到尤其是文档里的错误码说明。3. application.yml 里 base-url 与 api-key 的可复制配置这一节给出完整的可复制配置。假设你的 MCP Server 是基于spring-ai-starter-mcp-server-webmvc的 Spring Boot 应用端口 8081工具方法内部需要调用模型服务。配置分两块MCP Server 自身的配置和模型服务的鉴权配置。我把它们放在同一个application.yml里用注释分隔。server: port: 8081 spring: ai: # # MCP Server 自身配置 # mcp: server: enabled: true name: webmvc-mcp-server version: 1.0.0 type: SYNC # 注意这里的 base-url 是 MCP Server 端点路径前缀默认空 # 不要和下面模型服务的 base-url 混淆 # base-url: sse-endpoint: /sse sse-message-endpoint: /mcp/messages # SSE 模式下必须保持 false否则 /sse 端点不可用 stdio: false tool-change-notification: true resource-change-notification: true prompt-change-notification: true # # 模型服务鉴权配置统一 Key # # 这里用 openai 兼容的配置项作为示例 # 实际字段名以你使用的 SpringAI 版本为准 openai: # 统一模型服务基址不带 UTM 参数 base-url: https://taotoken.net/api # 从环境变量读取避免硬编码 api-key: ${TAOTOKEN_API_KEY} chat: options: # 模型 ID按你实际使用的填写 model: claude-sonnet-4-20250514 temperature: 0.7如果你用的是自定义的RestClient或WebClient在工具方法里直接调模型而不是走 SpringAI 的ChatClient那配置可以抽成一个独立的ConfigurationProperties类或者直接在application.yml里定义自定义前缀taotoken: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} model: claude-sonnet-4-20250514然后在工具类里注入Component public class MyChatTools { Value(${taotoken.base-url}) private String baseUrl; Value(${taotoken.api-key}) private String apiKey; Value(${taotoken.model}) private String model; private final WebClient webClient; public MyChatTools(WebClient.Builder builder) { this.webClient builder.build(); } Tool(description 调用模型生成一段文本) public String generateText(ToolParam(description 提示词) String prompt) { MapString, Object body Map.of( model, model, messages, List.of(Map.of(role, user, content, prompt)) ); return webClient.post() .uri(baseUrl /v1/chat/completions) .header(Authorization, Bearer apiKey) .header(Content-Type, application/json) .bodyValue(body) .retrieve() .bodyToMono(String.class) .block(); } }这里的关键点是base-url和api-key只在一处定义所有工具方法共享。如果你有多个工具类把它们都注入同一个配置而不是各写各的。这样联调时只需要确认一个环境变量TAOTOKEN_API_KEY是否正确不用逐个文件检查。提示base-url末尾不要带斜杠https://taotoken.net/api是正确的https://taotoken.net/api/在某些 HTTP 客户端里会拼出双斜杠虽然多数情况能容错但联调时少一个变量少一份心累。配置写完后启动应用。如果TAOTOKEN_API_KEY没有设置Spring 启动时会因为占位符解析失败而报错这其实是好事——早失败早发现比运行到工具调用时才报 401 要好。你可以在 IDE 的 Run Configuration 里加环境变量或者在 shell 里export TAOTOKEN_API_KEYsk-你的key后再启动。4. 启动后通过 /mcp 端点发起工具调用验证配置就位后下一步是验证请求确实经统一 Key 通道正常返回。验证分两个层次先确认 MCP Server 的/sse端点能连上再通过 MCP Client 发起一次工具调用观察工具方法内部的模型请求是否成功。先启动应用export TAOTOKEN_API_KEYsk-你的key mvn spring-boot:run启动日志里应该能看到 MCP Server 注册的工具列表以及类似Registered tools: [generateText, currentDateTime]的输出。如果看到spring.ai.mcp.server.stdio相关的警告检查一下是不是误设成了true。然后写一个 MCP Client 的单元测试用 SSE 传输协议连接/sse端点调用工具Test void testGenerateTextTool() { // 使用 SSE 传输协议初始化 MCP Client McpClientTransport transport HttpClientSseClientTransport .builder(http://localhost:8081) .build(); McpSyncClient client McpClient.sync(transport) .requestTimeout(Duration.ofSeconds(30)) .build(); client.initialize(); // 调用工具 generateText CallToolResult result client.callTool( new CallToolRequest(generateText, Map.of(prompt, 用一句话介绍 MCP 协议)) ); Boolean error result.isError(); log.info(Call Tool generateText error: {}, error); Assertions.assertFalse(error, 工具调用失败); ListContent contents result.content(); TextContent textContent (TextContent) contents.get(0); log.info(Tool result: {}, textContent.text()); client.closeGracefully(); }运行这个测试如果一切正常控制台会打印出模型返回的文本。这时候去看 MCP Server 的日志应该能看到工具方法内部的 HTTP 请求记录请求地址是https://taotoken.net/api/v1/chat/completions请求头里带着Authorization: Bearer sk-...。这就证明请求确实经统一 Key 通道发出并正常返回了。如果你想更直观地验证可以用 curl 直接打 MCP Server 的/sse端点确认 SSE 连接建立curl -N http://localhost:8081/sse正常的话会看到event: endpoint和data: /mcp/messages?sessionId...这样的输出说明 SSE 通道已就绪。然后你可以用这个 sessionId 向/mcp/messages发一个 JSON-RPC 请求手动触发工具调用。不过手动构造 JSON-RPC 比较繁琐用上面的单元测试更省事。验证成功的标志有三个MCP Client 的initialize返回了 Server 的 capabilitiescallTool返回的isError是false工具返回的文本内容非空且符合预期。三个都满足说明从 MCP Client 到 MCP Server 再到 TaoToken 统一 Key 通道的整条链路是通的。注意如果工具方法内部调模型超时callTool会返回isErrortrue但错误信息可能被 MCP 协议包装过看起来不够直观。这时候去 MCP Server 的应用日志里找原始异常通常能看到具体的 HTTP 状态码和错误体。5. 本篇常见错排查401、local proxy failed 与 reading choices联调时最常见的报错就那么几个逐个说清楚原因和排查动作。401 Unauthorized。这是最直接的鉴权失败。先确认TAOTOKEN_API_KEY环境变量是否真的传进了应用进程。在 IDE 里跑和在 shell 里跑环境变量的作用域不一样IDE 的 Run Configuration 需要单独设置。确认方法是在工具方法里打一行日志log.info(apiKey prefix: {}, apiKey.substring(0, 8))看前缀是不是sk-开头。如果前缀对但依然 401检查 Key 是否过期或被禁用去控制台的 API Keys 页面确认状态。还有一种情况是base-url配错了请求打到了错误的域名返回的 401 可能来自另一个服务。local proxy failed。这个报错通常出现在 HTTP 客户端尝试连接base-url时底层网络层无法建立连接。排查顺序先确认base-url拼写正确https://taotoken.net/api没有多余字符再确认本机网络能正常访问该域名可以用curl -v https://taotoken.net/api/v1/models测试如果 curl 能通但 Java 应用不通检查应用是否配置了额外的 HTTP 代理或者 JVM 参数里有没有-Dhttp.proxyHost之类的设置。本地开发环境里有时候 IDE 的代理设置会覆盖系统设置导致 Java 进程走了错误的代理。reading choices 相关报错。这个报错通常出现在解析模型响应时错误信息里带reading choices或Cannot read field choices。原因是请求虽然返回了 200但响应体结构不是预期的 OpenAI 兼容格式可能是错误信息被包装成了正常响应或者base-url指向了一个返回 HTML 的地址。排查方法在工具方法里把原始响应体打印出来看是不是 JSON。如果是 HTML说明base-url或路径拼错了请求打到了官网页面而不是 API 端点。确认路径是base-url /v1/chat/completions且base-url是https://taotoken.net/api。OAuth 相关报错。如果你在 MCP Client 侧配置了 OAuth 鉴权但 MCP Server 侧没有对应处理会出现OAuth token missing或invalid_token。MCP 协议本身支持 OAuth但 SpringAI 的 MCP Server Boot Starter 默认不启用 OAuth。如果你不需要 OAuth确认 Client 侧没有强制要求如果需要得在 Server 侧加对应的过滤器。多数本地联调场景下MCP Server 的鉴权就是简单的 Bearer Token不需要 OAuth 流程。SSE 端点 404。这个不是鉴权问题但经常和鉴权问题一起出现。原因是spring.ai.mcp.server.stdio被设成了true导致 Web 服务没有正常暴露/sse。确认配置里stdio: false或者干脆不写这一项默认 false。如果你确实需要同时支持 SSE 和 STDIOSSE 模式下必须保持stdio: falseSTDIO 模式通过命令行参数-Dspring.ai.mcp.server.stdiotrue单独开启。工具调用返回空内容。callTool的isError是false但content列表为空或文本为空。这种情况通常是工具方法内部捕获了异常但没有正确返回或者模型返回了空响应。检查工具方法里是否有try-catch吞掉了异常以及模型请求的max_tokens是否设得太小。另外如果用的是流式响应但工具方法按非流式解析也会出现空内容。排查时的一个实用技巧在 MCP Server 里加一个全局的ExceptionHandler把工具方法抛出的异常统一转成带错误信息的CallToolResult这样 MCP Client 侧能看到具体错误而不是一个笼统的isErrortrue。ExceptionHandler(Exception.class) public CallToolResult handleToolException(Exception e) { return new CallToolResult( List.of(new TextContent(工具调用失败: e.getMessage())), true ); }这样联调时错误信息直接透传到 Client省去来回翻日志的时间。6. 把统一 Key 通道固化到你的 MCP 开发流程里配置和验证跑通之后剩下的事情就是把它固化下来让下次联调不用重新踩坑。几个实用动作把TAOTOKEN_API_KEY写进项目的.env.example文件只写变量名不写值提醒协作者配置在application.yml里用${TAOTOKEN_API_KEY}占位确保 key 不进版本库把base-url和model抽成配置项换模型时只改一处。如果你后续要做更复杂的 MCP Server比如同时暴露多个工具、需要 Sampling 能力、或者要接 Claude Code 做编码辅助统一 Key 通道的价值会更明显。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。长期做编码和 Agent 开发的话Coding Plan 入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 可以按需了解。最后留一个我踩过的坑MCP Server 的sse-message-endpoint默认是/mcp/messages但有些 MCP Client 默认按/mcp去发消息导致 404。如果你遇到 Client 连上/sse但发消息失败检查一下 Client 侧的消息端点配置或者把 Server 侧的sse-message-endpoint改成 Client 期望的路径。这个和鉴权无关但联调时经常和鉴权问题混在一起浪费排查时间。