1. 从一次“工具没被调用”的排查说起Spring AI MCP 是什么简单说它把 Model Context Protocol 这套“模型和外部工具对话的约定”封装进了 Spring 生态让你用几个 Bean 和一段 yml 就能把 Java 方法暴露成模型可调用的工具。它适合谁适合已经在写 Spring Boot、想让大模型真正“动手干活”查库、调接口、算数据而不是只聊天的 Java 开发者。我最初跑官方 demo 时遇到一个很典型的现象模型回复得头头是道但日志里始终没有工具执行记录/sse连上了/mcp/message也返回 200可工具就是没触发。后来发现是工具注册的 Bean 没被ToolCallback收集到加上模型侧压根没拿到工具定义。这类“链路看着通、实际没打通”的问题正是本篇要带你复现并验证的核心。下面我会按“最小可运行示例”的思路走一遍先给application.yml和 MCP 客户端配置骨架再接入 TaoToken 的统一 Key/API 通道最后用一次真实请求确认工具调用链是否闭环。全程本机可跑不需要复杂环境。2. TaoToken 前置统一 Key 与 API 通道在动手写 MCP 之前先把模型访问这一层理顺。Spring AI 支持多种模型后端但配置项分散、Key 管理麻烦。TaoToken 提供统一的 API 通道一个 Key 就能对接多种模型省去在多个平台之间来回切换配置的功夫。你需要先拿到 Key进入控制台创建 API Key地址是 https://taotoken.net/console 。创建后复制保存后面写进application.yml的环境变量里。如果你还没决定用哪个模型可以先去模型对话页面体验一下不同模型的表现地址 https://taotoken.net/model-chat 确认哪个更适合你的工具调用场景。这里要强调一点MCP 的工具调用对模型的“函数调用/工具调用”能力有要求选模型时优先挑支持 tool calling 的。TaoToken 的 API 端点统一为 https://taotoken.net/api 在 Spring AI 里配置base-url时指向它即可不需要额外拼路径。注意Key 不要硬编码进代码提交到仓库用环境变量注入这是基本的安全习惯。3. 可复制配置application.yml 与 MCP 客户端骨架先建一个标准的 Spring Boot 3.x 工程依赖里加上spring-ai-starter-mcp-client和对应模型 starter。下面是application.yml的骨架重点看 MCP 客户端和模型两部分的配置。server: port: 8080 spring: ai: # 模型通道统一走 TaoToken openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.2 # MCP 客户端配置 mcp: client: enabled: true name: demo-mcp-client version: 1.0.0 # 连接本机启动的 MCP ServerSSE 传输 sse: connections: local-server: url: http://localhost:8081 sse-endpoint: /sse这里TAOTOKEN_API_KEY通过环境变量传入启动命令里带上即可export TAOTOKEN_API_KEY你的Key ./mvnw spring-boot:runMCP 客户端的核心是McpClientAutoConfiguration它会根据你配置的sse.connections自动建立连接并完成协议版本协商、能力协商、工具发现。你不需要手写连接代码Spring 会在启动时把远端 Server 暴露的工具注册成可调用的ToolCallback。如果你要做的是“本机最小示例”建议同时起一个 MCP Server端口 8081客户端8080连过去。Server 端可以用spring-ai-starter-mcp-server-webmvc暴露一个简单工具比如查询当前时间或做加法。这样客户端启动后就能在日志里看到工具发现的结果。4. 工具注册、调用与返回结果的逐步验证配置写完接下来是验证链路是否真的打通。分三步走每步都有可观察的结果。4.1 确认工具被发现启动客户端后在日志里搜索tools或discovered。正常情况下你会看到类似Discovered N tools from server local-server的输出。如果 N 是 0说明 Server 端没注册工具或者连接没建立成功。这一步是很多“链路不通”问题的分水岭。4.2 写一个触发工具调用的接口在客户端工程里加一个简单的 Controller把用户问题转给ChatClient并开启工具调用RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient.Builder builder) { this.chatClient builder .defaultSystem(你可以调用工具来完成任务。) .build(); } GetMapping(/ask) public String ask(RequestParam String q) { return chatClient.prompt() .user(q) .call() .content(); } }Spring AI 会自动把已发现的 MCP 工具注入到ChatClient的调用上下文中。你不需要手动传工具列表前提是工具发现成功。4.3 发一次真实请求并看返回假设 Server 端注册了一个add工具接受两个整数。请求curl http://localhost:8080/ask?q帮我算一下 37 加 58 等于多少预期结果模型不会直接口算而是返回一个工具调用请求客户端执行后把结果回传最终返回类似“37 加 58 等于 95”。同时 Server 端日志会打印工具执行记录。如果你在 Server 端工具方法里加了System.out.println就能看到它被真正调用了。这一步的关键观察点有三个模型是否发起了工具调用、客户端是否转发了执行请求、Server 是否返回了结果。三者缺一链路就没闭环。5. 本篇常见错排查实际跑的时候下面几个坑出现频率最高我按现象、原因、解法列出来。现象可能原因解法日志显示发现 0 个工具Server 端工具未注册为 Bean确认工具方法所在类被Component扫描且返回ToolCallback模型直接回答不调工具模型不支持 tool calling 或未传工具定义换支持工具调用的模型确认ChatClient开启了工具连接/sse超时Server 未启动或端口不对先单独启动 Servercurl http://localhost:8081/sse看是否挂起工具调用报参数解析失败工具入参 schema 与请求不匹配检查工具方法的参数类型和ToolParam描述401/403Key 未注入或 base-url 写错确认环境变量生效base-url 为 https://taotoken.net/api排查顺序建议从“工具发现”开始再到“模型是否发起调用”最后看“Server 是否执行”。这样能快速定位是配置层、模型层还是 Server 层的问题。如果你在接入文档里找不到对应说明可以对照 https://taotoken.net/doc 的接口约定检查请求格式。6. 把链路跑通之后工具调用链一旦闭环后面扩展就顺了加新工具只需在 Server 端注册新 Bean客户端重启后自动发现模型侧无需改动。如果你打算长期做编码类或 Agent 类项目频繁调用模型和工具可以了解下 Coding Plan地址 https://taotoken.net/coding-plan 按需选择更合适的额度方案。回到本篇的目标你要的不是“看起来能跑”而是“确认真的打通”。判断标准很简单——Server 端日志里出现了工具执行记录且最终回答里包含了工具返回的数据。只要这两点满足Spring AI MCP 的链路就算真正跑通了。