1. 为什么 Java 开发者需要自己搭一套 MCP Server 和 MCP ClientMCPModel Context Protocol说白了就是给大模型装一个「工具插座」。模型本身只会聊天但通过 MCP 协议它可以调用你写的 Java 方法、查你的数据库、读你的内部接口。对 Java 开发者来说Spring AI 已经把 MCP 的协议细节封装好了你只需要写业务方法、暴露 SSE 端点剩下的握手、能力协商、工具注册都由框架处理。但真正动手时问题往往不在协议本身而在「鉴权配置分散」。我见过太多项目MCP Server 里写一份模型 KeyMCP Client 里又写一份本地联调时两边环境变量对不上报 401 报得莫名其妙。更麻烦的是Server 和 Client 可能用不同厂商的模型Key 格式、Base URL 都不一样改一处忘一处。这篇要解决的就是这个场景用 TaoToken 的统一 Key让 MCP Server 和 MCP Client 共用一套鉴权配置SSE 方式跑通双端联调。TaoToken 是一个模型 API 聚合服务提供统一的 Base URL 和 Key兼容 OpenAI 风格的接口Spring AI 的 OpenAI starter 可以直接对接。你不需要在 Server 和 Client 里分别维护不同厂商的 Key改一个地方两端都生效。适合谁看已经会用 Spring Boot、想快速验证 MCP 工具调用链路的 Java 开发者正在做本地 Agent 联调、被多套 Key 折腾过的后端同学以及想把内部 Java 服务暴露成 MCP 工具、让 AI 客户端调用的团队。整条链路是这样的MCP Server 用 Spring AI 的 webmvc starter 暴露 SSE 端点注册Tool注解的方法MCP Client 用 webflux starter 订阅这个 SSE 端点把远端工具挂到自己的 ChatClient 上模型调用走 TaoToken 统一 Key。下面从环境准备开始一步步给可复制的配置和代码。2. TaoToken 统一 Key 的前置准备与 application.yml 配置先说清楚 TaoToken 在这套架构里的位置。它不是替代 Spring AI而是替代「模型提供方」这一层。原来你可能在 Client 里配智谱、在 Server 里配另一个厂商现在两端都指向 TaoToken 的 Base URL用同一个 Key。这样本地联调时鉴权配置只有一处需要改。你需要先拿到 Key。访问 TaoToken 控制台创建 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建后复制保存后面配置里用环境变量引用不要硬编码进代码。TaoToken 的 API Base URL 是 https://taotoken.net/api 注意这个地址不带任何查询参数直接作为base-url使用。模型 ID 按你实际需要的填比如gpt-4o-mini、claude-3-5-sonnet这类具体以控制台模型列表为准。先看 MCP Server 端的application.yml。Server 本身不一定需要调模型但如果你的工具方法内部要调模型比如做摘要、做分类就需要配。这里给出统一配置server: port: 8080 spring: application: name: math-mcp-server ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini mcp: server: enabled: true name: math_mcp_server version: 1.0.0 sse-endpoint: /api/v1/sse sse-message-endpoint: /api/v1/mcp capabilities: tool: true logging: level: io.modelcontextprotocol: TRACE org.springframework.ai.mcp: TRACE关键点base-url写https://taotoken.net/api不要加/v1之类的后缀Spring AI 的 OpenAI starter 会自己拼路径。api-key用${TAOTOKEN_API_KEY}从环境变量读本地开发在 IDEA 的 Run Configuration 里加环境变量或者用.env文件配合插件。再看 MCP Client 端的application.ymlserver: port: 8081 spring: application: name: test-mcp-client ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini mcp: client: sse: connections: math-server: url: http://localhost:8080 sse-endpoint: /api/v1/sse logging: level: io.modelcontextprotocol: TRACE org.springframework.ai.mcp: TRACE两端用的是同一个${TAOTOKEN_API_KEY}同一个base-url。这就是「统一 Key」的核心改 Key 只改环境变量两个工程的 yml 都不用动。如果你之前用智谱的 starter现在换成spring-ai-starter-model-openai因为 TaoToken 兼容 OpenAI 接口风格。环境变量设置方式Linux/macOSexport TAOTOKEN_API_KEY你的KeyWindows PowerShell$env:TAOTOKEN_API_KEY你的KeyIDEA 里更稳妥的做法是在 Run/Debug Configurations 的 Environment variables 里填TAOTOKEN_API_KEY你的Key这样每个工程独立不会互相污染。3. MCP Server 端可复制配置pom、Tool 类与 SSE 端点暴露这一节给完整的可复制片段。先看pom.xml核心是把默认的spring-ai-starter-mcp-server换成spring-ai-starter-mcp-server-webmvc因为我们要用 SSE 方式暴露 HTTP 端点?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.5.8/version relativePath/ /parent groupIdcom.example/groupId artifactIdmath-mcp-server/artifactId version0.0.1-SNAPSHOT/version properties java.version17/java.version spring-ai.version1.1.2/spring-ai.version /properties dependencies 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 dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin /plugins /build /project工具类MathTool用Tool注解描述方法模型靠 description 判断什么时候调用package com.example.tool; import org.springframework.ai.tool.annotation.Tool; public class MathTool { Tool(description 两个数字相加返回和) public static int addNumbers(int a, int b) { return a b; } Tool(description 两个数字相减返回差) public static int subtractNumbers(int a, int b) { return a - b; } }配置类把工具注册成ToolCallbackProviderpackage com.example.config; import com.example.tool.MathTool; import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.ai.tool.method.MethodToolCallbackProvider; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class McpConfig { Bean public ToolCallbackProvider mathTool() { return MethodToolCallbackProvider.builder() .toolObjects(new MathTool()) .build(); } }启动类保持默认即可。启动后SSE 端点暴露在http://localhost:8080/api/v1/sse消息端点http://localhost:8080/api/v1/mcp。日志里会看到注册了两个 Toolio.modelcontextprotocol的 TRACE 日志会打印握手过程。这里有个容易踩的坑sse-endpoint和sse-message-endpoint必须和 Client 端配置的路径完全一致大小写、斜杠都不能差。我试过把 Server 写成/api/v1/sse、Client 写成/api/v1/SSE结果 Client 一直连不上日志只报连接超时排查了半天。4. MCP Client 端订阅 SSE 与 curl 验证事件流Client 端的pom.xml核心依赖是spring-ai-starter-mcp-client-webflux和spring-ai-starter-model-openaidependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client-webflux/artifactId /dependency /dependenciesController 把远端工具挂到 ChatClient 上package com.example.controller; import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.tool.ToolCallbackProvider; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/mcp) public class ConnectMcpServer { private final ChatClient chatClient; public ConnectMcpServer(ChatClient.Builder builder, ToolCallbackProvider toolCallbackProvider) { this.chatClient builder .defaultToolCallbacks(toolCallbackProvider.getToolCallbacks()) .build(); } GetMapping(/test) public String test(RequestParam(name query) String query) { return chatClient.prompt() .system(你是一个有用的AI助手需要计算时调用工具) .user(query) .call() .content(); } }启动 Client 后先别急着调接口用 curl 验证 SSE 事件流是否正常。SSE 端点是长连接curl 要加-N禁用缓冲curl -N http://localhost:8080/api/v1/sse正常会看到类似这样的输出event: endpoint告诉你后续消息往哪个地址发event: endpoint data: /api/v1/mcp?sessionIdabc123拿到sessionId后可以手动发一个初始化请求验证工具列表curl -X POST http://localhost:8080/api/v1/mcp?sessionIdabc123 \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}返回里应该能看到addNumbers和subtractNumbers两个工具的定义。这一步能过说明 Server 端工具注册没问题。然后调 Client 的测试接口curl http://localhost:8081/mcp/test?query8加6等于几预期返回类似「8 加 6 等于 14」。同时看 Server 端日志会打印工具调用记录io.modelcontextprotocol的 TRACE 日志里能看到tools/call的请求和响应。Client 端日志会显示 SSE 连接建立、工具列表拉取、模型决策调用工具的过程。如果模型没有调用工具而是直接回答检查两点一是Tool的 description 是否清晰二是 system prompt 里有没有引导「需要计算时调用工具」。TaoToken 的模型对工具调用的支持取决于具体模型选支持 function calling 的模型 ID。5. 双端联调常见报错排查401、local proxy failed、reading choices联调时最容易卡在几个固定报错上这里逐个对照。401 Unauthorized。最常见的原因是TAOTOKEN_API_KEY环境变量没生效。先确认启动日志里没有把 Key 打成空字符串。可以在 Controller 里临时打印System.getenv(TAOTOKEN_API_KEY)的前几位验证。另一个原因是base-url写错比如写成了https://taotoken.net/api/v1Spring AI 会拼成/v1/v1/chat/completions服务端返回 401 或 404。正确写法就是https://taotoken.net/api。local proxy failed / Connection refused。这是 Client 连不上 Server 的 SSE 端点。检查 Server 是否真的启动了curl -N http://localhost:8080/api/v1/sse能不能出事件。如果 Server 在 Docker 里localhost要换成容器网络里的地址。端口冲突也会导致这个问题Server 默认 8080Client 默认 8081别搞反。reading choices 相关报错。通常是模型返回体解析失败原因可能是模型 ID 不存在或者 TaoToken 那边模型列表里没有你填的 ID。去控制台确认模型 ID 拼写注意有些模型有版本后缀。另一个可能是请求超时SSE 长连接和模型调用叠加默认超时不够可以在 yml 里加spring: ai: openai: chat: options: timeout: 60000OAuth / 鉴权头冲突。如果你之前配过其他厂商的 starter残留的自动配置可能还在生效导致请求带了两个 Authorization 头。检查pom.xml里是不是同时有spring-ai-starter-model-zhipuai和spring-ai-starter-model-openai有的话删掉不用的那个。Spring AI 的自动配置是按 starter 触发的多个模型 starter 共存会打架。工具调用返回空 / 模型说「我没有计算能力」。说明工具没挂上。检查 Client 的ToolCallbackProvider是否注入成功defaultToolCallbacks是否真的拿到了工具列表。可以在构造函数里打印toolCallbackProvider.getToolCallbacks().length正常应该是 2。如果为 0说明 SSE 连接没建立回到上一条排查连接问题。SSE 事件流断连。长连接容易被中间层掐断本地开发一般没事但如果经过网关要确认网关支持 SSE 且没有缓冲。curl 测试时如果一直挂起没有输出加-v看握手细节。排查顺序建议先 curl Server 的 SSE 端点确认事件流正常再 curl Client 的测试接口确认模型能调工具最后看两端日志里的tools/call记录。这样能把问题定位到具体哪一段。6. 从本地联调到长期编码把统一 Key 用起来跑通之后你会发现统一 Key 的价值不只是省事。本地联调时Server 和 Client 共用一套鉴权改环境变量就切换模型不用动代码。这对做 Agent 类项目特别有用你可能今天用便宜模型跑通链路明天换强模型验证效果Key 和 Base URL 都不变。如果你要把这套东西用到长期编码或 Agent 场景TaoToken 的 Coding Plan 值得看一下地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合需要稳定调用、按量计费的开发场景。模型对话调试可以用 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速验证某个模型对工具调用的支持程度。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言 SDK 的配置示例。回到代码本身有几个实用技巧。第一把TAOTOKEN_API_KEY和TAOTOKEN_BASE_URL都做成环境变量yml 里只写${TAOTOKEN_BASE_URL}这样切换环境不用改文件。第二MCP Server 的工具方法尽量保持无状态、幂等因为模型可能重试调用。第三SSE 端点路径加上版本号比如/api/v1/sse后续协议升级时好做兼容。最后说一个我踩过的坑Client 端用 webflux starter 时如果项目里同时引入了spring-boot-starter-web可能会有冲突。Spring AI 的 MCP Client webflux starter 需要响应式栈但 Controller 又用了阻塞式的RestController。实测下来只要不引入spring-boot-starter-webflux的自动配置冲突spring-boot-starter-web和 MCP Client webflux 可以共存因为 MCP 的 SSE 连接是内部管理的。如果启动报WebApplicationType相关错误把spring.main.web-application-typeservlet显式配上。整套跑通后你可以把MathTool换成任何业务方法查订单、调内部 API、读配置中心。MCP 协议负责把 Java 方法暴露给模型TaoToken 负责统一鉴权Spring AI 负责胶水。三者各司其职本地联调不再被 Key 分散的问题卡住。