1. Spring AI 接 MCP Server 时Key 和通道为什么总是散落一地如果你正在用 Spring AI 写一个能调用外部工具的智能应用大概率已经踩过这样的坑模型走一个 API Key文件系统 MCP Server 走 stdioExcel 的 MCP Server 走 SSE数据库的 MCP Server 又是另一个地址。每接一个工具就要在application.yml里多塞一组地址和密钥改到最后自己都记不清哪个 Key 对应哪个服务。MCPModel Context Protocol本身是为了让大模型能标准化地调用外部工具而设计的协议Spring AI 也提供了spring-ai-starter-mcp-client来对接 MCP Server。但协议统一了接入层的凭证和通道却没有统一。模型侧要配 OpenAI 兼容的base-url和api-keyMCP Server 侧又要配各自的连接方式一个入门 Demo 就能把配置文件撑到几十行。这篇要解决的就是这个分散问题用 TaoToken 的统一 Key 和统一 API 地址把 Spring AI 应用里模型调用的凭证收敛成一份MCP Server 的连接配置保持清晰分层。跑通之后你换模型、加工具只需要动一处配置。适合刚接触 Spring AI MCP、想快速跑通一次工具调用链路的同学也适合已经被多 Key 管理折腾过的开发者。下面从依赖、配置骨架、代码到验证一步步来每一步都给可复制的内容。2. TaoToken 前置把模型通道先统一掉在写 MCP 配置之前先把模型这一侧的通道固定下来。Spring AI 的 OpenAI Starter 本质上走的是 OpenAI 兼容接口规范所以只要有一个兼容 OpenAI 的base-url和api-key就能驱动OpenAiChatModel。TaoToken 提供的正是这样一个统一入口一个 Key 覆盖多种模型API 地址固定不用为每个模型单独申请凭证。你需要先拿到两样东西一是 API Key。登录 TaoToken 控制台在 API Keys 页面创建一个新 Key复制出来备用。这个 Key 后面会写进application.yml的spring.ai.openai.api-key。二是确认 API 地址。TaoToken 的 API 根地址是https://taotoken.net/api注意这里不要带任何查询参数Spring AI 会在这个根地址后面拼接/v1/chat/completions这类路径。如果你在别处看到带 UTM 的链接那是给网页访问用的配置里只写纯 API 地址。模型名称方面TaoToken 支持多种主流模型你在spring.ai.openai.chat.options.model里填对应模型标识即可。入门阶段建议先用一个你熟悉的对话模型把链路跑通确认 MCP 工具调用没问题之后再换其他模型对比效果。这一步做完模型侧的凭证就只有一个 Key、一个地址。接下来 MCP Server 的连接配置就可以专注在“工具怎么连”上不再和模型凭证混在一起。3. 可复制配置pom 依赖与 application.yml 骨架3.1 Maven 依赖Spring AI 的版本迭代比较快这里用1.0.0-M7作为示例JDK 用 17。核心依赖有三个Web 起步依赖、MCP Client Starter、OpenAI 模型 Starter。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.4.4/version relativePath/ /parent groupIdsite.sunlong/groupId artifactIdmcp-client/artifactId version0.0.1-SNAPSHOT/version properties java.version17/java.version spring-ai.version1.0.0-M7/spring-ai.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-client/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /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这里选的是spring-ai-starter-mcp-client而不是 webflux 版本。两者的区别在于前者同时支持 stdio 和基于 HTTP 的 SSE 调用后者是响应式 SSE 专用。入门阶段用前者覆盖面更广一个依赖就能把 stdio 和 SSE 两种 MCP Server 都接上。3.2 application.yml 配置骨架这是本篇的核心配置。模型侧用 TaoToken 统一 Key 和地址MCP 侧按连接方式分层。spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: your-model-name mcp: client: type: SYNC request-timeout: 1800s toolcallback: enable: true stdio: servers-configuration: classpath:mcp-servers.json sse: connections: excel-mcp-server: url: http://localhost:8000 jdbc-mcp-server: url: http://localhost:9090几个关键点解释一下。base-url写 TaoToken 的 API 根地址api-key用环境变量注入避免把 Key 硬编码进仓库。你在本地运行时设置环境变量TAOTOKEN_API_KEY即可IDEA 里可以在 Run Configuration 的 Environment variables 里填。request-timeout设成 1800s 是有原因的。MCP 工具调用涉及模型推理加工具执行链路比普通对话长尤其当工具本身要查数据库或写文件时短超时很容易在工具执行到一半时断开。设长一点成功率高很多。toolcallback.enable设为 true让 Spring AI 自动把 MCP Client 发现的工具注册成模型可调用的回调。这样你在代码里不用手动一个个注册工具MCP Server 暴露什么模型就能用什么。stdio.servers-configuration指向一个 JSON 文件描述用 stdio 方式启动的 MCP Server。SSE 方式的 Server 则直接在sse.connections下写 URL注意 URL 后面不要加/sse后缀Spring AI 会自己拼接。3.3 stdio 的 mcp-servers.json放在src/main/resources/mcp-servers.json{ mcpServers: { server-filesystem: { command: npx.cmd, args: [ -y, modelcontextprotocol/server-filesystem, D:\\projects\\excel-mcp-server-main\\excel_files ] } } }这个配置启动的是 Node.js 版的文件系统 MCP Server允许模型读写指定目录下的文件。command在 Windows 下用npx.cmdLinux 或 macOS 下改成npx。路径按你自己的实际目录改。如果你不想用外部 JSON 文件也可以把 stdio 连接直接写在application.yml的spring.ai.mcp.client.stdio.connections下但 JSON 文件的方式更清晰多个 Server 时尤其明显。4. 验证请求一次 MCP 工具调用的完整链路4.1 注入 ChatClient 并挂载 MCP 工具配置写好后需要一个ChatClientBean把 MCP 工具回调挂上去。Configuration public class McpClientConfiguration { Bean ChatClient chatClient(OpenAiChatModel chatModel, ListMcpSyncClient mcpClients) { var mcpToolProvider new SyncMcpToolCallbackProvider(mcpClients); return ChatClient.builder(chatModel) .defaultTools(mcpToolProvider) .build(); } }ListMcpSyncClient会被 Spring AI 自动注入里面是当前配置的所有 MCP Client。SyncMcpToolCallbackProvider把这些 Client 暴露的工具统一包装成模型可调用的回调。defaultTools一挂后面每次对话模型都能看到这些工具。4.2 写一个测试接口RestController RequestMapping(/mcp) public class McpChatController { Autowired private ChatClient chatClient; GetMapping(/generate) public MapString, String generate(RequestParam(message) String message) { String content this.chatClient.prompt() .user(message) .call() .content(); return Map.of(generation, content); } }4.3 发起验证请求启动应用后先确认 MCP Server 已经连上。文件系统的 Server 是 stdio 方式应用启动时就会拉起子进程SSE 方式的 Server 需要你提前把对应的服务跑起来。然后发一个请求让模型在指定目录下创建一个文件curl http://localhost:8080/mcp/generate?message请在D:/projects/excel-mcp-server-main/excel_files目录下创建一个mcp.txt文件内容写hello mcp如果链路通了你会看到两件事一是接口返回一段模型生成的文字说明它调用了文件系统工具二是去D:/projects/excel-mcp-server-main/excel_files目录下看mcp.txt文件已经存在内容就是hello mcp。这一步验证的是“模型 → MCP Client → MCP Server → 实际工具执行”的完整链路。模型负责理解你的意图并决定调用哪个工具MCP Client 负责把工具调用翻译成 MCP 协议请求MCP Server 负责真正执行文件操作。4.4 多 Server 综合验证单个工具跑通后可以试试多个 MCP Server 配合。比如同时接文件系统和数据库两个 Server然后发一个跨工具的任务curl http://localhost:8080/mcp/generate?message先在excel_files目录下创建db.xlsx然后查询数据库中i18n_msg表的数据把结果写入db.xlsx模型会先调用文件系统工具创建 Excel 文件再调用数据库工具查询最后把数据写回文件。这个过程里TaoToken 的统一 Key 只负责模型推理这一段MCP Server 的连接各自独立互不干扰。这也是把模型凭证和工具连接分开配置的好处换模型不影响工具加工具不影响模型。5. 本篇常见错排查5.1 stdio 方式启动 Java 版 MCP Server 失败有同学试过用 stdio 方式启动一个 Spring Boot 打包的 Java MCP Server配置大概是这样{ mcpServers: { jdbc-mcp-server: { command: java, args: [ -Dspring.ai.mcp.server.stdiotrue, -Dspring.main.banner-modeoff, -Dspring.main.web-application-typenone, -jar, D:\\projects\\jdbc-mcp-server\\target\\jdbc-mcp-server-0.0.1-SNAPSHOT.jar ] } } }启动后报解析错误。排查下来问题出在 Java 进程的控制台输出上。MCP 的 stdio 协议要求子进程的 stdout 只输出符合协议格式的 JSON 消息但 Spring Boot 应用启动时会打印 banner、日志、启动信息这些内容混进了 stdoutMCP Client 解析时就崩了。对比一下正常的 Node.js 版 Server它的 stdout 是干净的只有协议消息。而 Java 版即使加了banner-modeoff日志框架默认还是往控制台输出。可行的方向是把日志重定向到文件或者用logging.file.name把日志写走确保 stdout 只剩协议消息。如果只是入门验证建议先用 SSE 方式接 Java 版 Server省去 stdout 污染的麻烦。5.2 引入 webflux 依赖后启动报错把spring-ai-starter-mcp-client换成spring-ai-starter-mcp-client-webflux后应用启动直接失败。这个在 Spring AI 1.0.0-M7 阶段比较常见webflux 版本和 web 版本在自动配置上有冲突同时引入会触发 Bean 定义冲突。入门阶段不需要响应式 SSE用spring-ai-starter-mcp-client就够了它已经支持 SSE 连接。等 Spring AI 正式版发布后这类依赖冲突问题应该会收敛。5.3 工具调用超时或模型不调用工具如果请求返回很慢甚至超时先检查request-timeout是不是设得太短。MCP 工具调用链路长默认超时往往不够。如果模型压根不调用工具检查toolcallback.enable是否为 true以及ChatClient构建时有没有挂defaultTools。另外模型本身要支持 function calling部分轻量模型对工具调用的支持不完整换一个支持工具调用的模型再试。5.4 SSE 连接地址写错spring.ai.mcp.client.sse.connections.xxx.url只写到主机和端口不要加/sse或/mcp后缀。Spring AI 会按 MCP 协议规范自己拼接路径。多写后缀会导致连接 404。6. 把 Key 收拢之后下一步怎么走跑通这篇的链路后你手里应该有一个能调用 MCP 工具的 Spring AI 应用模型凭证收敛在 TaoToken 一处MCP Server 连接按 stdio 和 SSE 分层配置。这个结构的好处是扩展成本低加一个新工具只在 MCP 配置里加一段换一个模型只改model字段。如果你接下来要验证不同模型对工具调用的支持情况可以直接在模型对话页面里试不用改代码就能对比效果。如果你打算把这个链路用到长期的编码辅助或 Agent 场景里Coding Plan 更适合持续跑工具调用的负载。接入过程中遇到 Key 或地址配置问题API Keys 页面和接入文档里有完整的参数说明。MCP 的价值在于让工具接入标准化而统一 Key 的价值在于让凭证管理不再成为负担。两者结合Spring AI 应用的工具生态才真正好维护。