1. 为什么 Spring AI MCP 值得你花时间折腾如果你正在用 Spring Boot 做 AI 应用大概率遇到过这种场景模型需要查数据库、调天气接口、读本地文件每个工具都得单独写一套 Function Call 适配代码。工具一多接口风格不统一维护成本直线上升。MCPModel Context Protocol就是来解决这个问题的——它用一套基于 JSON-RPC 的标准协议把模型和外部工具的连接方式统一起来做到“即插即用”。Spring AI 对 MCP 的支持已经比较成熟通过 Spring Boot Starter 就能快速搭建 MCP 客户端和服务端。你可以把它理解成一个“工具总线”模型不需要知道每个工具的具体实现只需要按 MCP 规范发起调用剩下的路由、参数传递、结果返回都由协议层处理。这对 Java 开发者来说非常友好因为你可以继续用熟悉的 Spring 生态来管理依赖和配置。这篇文章面向的是已经了解 Spring Boot、想快速把 MCP 集成落地的开发者。我会从实际项目出发给出可复制的application.yml和 MCP 客户端配置片段重点演示如何把 endpoint 改到 TaoToken 统一 Key/API 通道并完成连通性验证。过程中会涉及 JSON-RPC 通信链路、多工具调用的配置要点以及常见的调用失败排查方法。读完你就能在自己的项目里跑通一条完整的 MCP 调用链路。2. TaoToken 前置准备统一 Key 与 API 通道在开始配置之前先把 TaoToken 的接入信息准备好。TaoToken 提供统一的 API 通道你只需要一个 Key 就能访问多种模型省去分别申请和管理多个平台账号的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。具体操作步骤第一步打开官网注册并登录进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在这里你可以看到账户余额、调用统计等信息。第二步创建 API Key。进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点击创建新 Key复制保存好。这个 Key 就是后面配置里的api-key值。第三步确认你要使用的模型 ID。TaoToken 支持多种模型你可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 先测试一下模型是否可用确认模型名称后再写入配置。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频调用场景做了额度优化。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题可以对照查阅。这里要强调一点TaoToken 是合规的 API 统一通道你只需要按标准 HTTP 方式调用即可不需要任何额外网络配置。把 Base URL 设为https://taotoken.net/api带上你的 Key就能正常发起请求。3. 可复制配置application.yml 与 MCP 客户端片段这一节是核心直接给你可以复制到项目里的配置。假设你用的是 Spring Boot 3.x Spring AI 1.0.x先确认pom.xml里引入了 MCP 相关依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency然后是application.yml这里把模型 endpoint 指向 TaoTokenspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 mcp: client: enabled: true name: spring-ai-mcp-client version: 1.0.0 request-timeout: 30s type: SYNC servers-configuration: classpath:/mcp-servers.json注意base-url后面不要加/v1TaoToken 的 API 路径已经处理好直接写https://taotoken.net/api即可。api-key建议用环境变量注入不要硬编码在文件里。接下来是src/main/resources/mcp-servers.json定义你要连接的 MCP 服务{ mcpServers: { weather: { command: java, args: [-jar, /opt/mcp/weather-server.jar], env: { API_KEY: ${TAOTOKEN_API_KEY} } }, database: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, /data/app.db] } } }如果你要连接远程 SSE 模式的 MCP 服务把command换成url{ mcpServers: { remote-tools: { url: https://your-mcp-server.example.com/mcp/sse } } }配置完成后Spring AI 会自动扫描mcp-servers.json并建立连接。你可以在启动日志里看到类似Registered MCP client: weather的输出说明客户端已经识别到服务。关于模型 ID 的填写如果你用的是 Claude 系列模型名要写全比如claude-3-5-sonnet-20241022。TaoToken 的模型列表可以在模型对话页面确认避免写错导致 404。4. 验证请求从 JSON-RPC 链路到成功结果配置写好后写一个简单的 Controller 来验证整条链路是否通。核心是注入ChatClient和McpClient然后发起一次带工具调用的对话RestController public class McpTestController { private final ChatClient chatClient; private final McpClient mcpClient; public McpTestController(ChatClient.Builder builder, McpClient mcpClient) { this.chatClient builder.build(); this.mcpClient mcpClient; } GetMapping(/test/mcp) public String testMcp(RequestParam String city) { String prompt 请调用天气工具查询 city 的天气并返回温度。; return chatClient.prompt() .user(prompt) .tools(mcpClient.getTools()) .call() .content(); } }启动项目后用 curl 发起请求curl http://localhost:8080/test/mcp?cityBeijing如果一切正常你会看到类似北京当前温度 25℃风速 2m/s的返回。这背后发生了什么Spring AI 把用户 prompt 发给 TaoToken 的模型 endpoint模型判断需要调用天气工具于是通过 JSON-RPC 向 MCP 客户端发起tools/call请求MCP 客户端路由到weather服务执行拿到结果后再回传给模型模型最终生成自然语言回复。你也可以直接测试 MCP 客户端本身不经过模型GetMapping(/test/tool) public String testTool() { McpToolCallback callback mcpClient.getToolCallbacks().get(0); return callback.call({\latitude\:\39.9042\,\longitude\:\116.4074\}); }这个接口会直接返回工具执行结果用来确认 MCP 服务端是否正常工作。如果这一步失败问题就在 MCP 服务端或 JSON-RPC 通信层而不是模型调用层。实测下来TaoToken 的响应速度比较稳定JSON-RPC 链路在同步模式下延迟主要来自工具执行本身。如果你需要高并发可以把type改成ASYNC配合request-timeout调整超时时间。5. 常见报错排查401、local proxy failed、reading choices集成过程中最容易踩的坑集中在几个典型报错上这里逐一对照排查。401 Unauthorized这个最常见说明 API Key 没传对。检查application.yml里的api-key是否读到了环境变量可以在启动时打印System.getenv(TAOTOKEN_API_KEY)确认。另外注意 Key 有没有多余空格复制时容易带上换行符。如果用的是 TaoToken 的 Key确认它没有过期或被删除可以在 API Keys 页面重新生成一个。local proxy failed / connection refused这个报错通常出现在 MCP 客户端连接本地 stdio 服务时。检查mcp-servers.json里的command路径是否正确args里的 jar 包路径是否存在。如果是npx命令确认本机 Node.js 版本是否支持。还有一种情况是 MCP 服务启动超时把request-timeout从 30s 调到 60s 试试。reading choices 报错这个一般出现在模型返回结构解析阶段说明 TaoToken 返回的 JSON 格式和 Spring AI 预期的 OpenAI 格式有差异。检查base-url是否写成了https://taotoken.net/api/v1多写/v1会导致路径拼接错误。正确的写法就是https://taotoken.net/api。另外确认model名称是否在 TaoToken 支持列表里写错模型名有时会返回非标准错误结构。OAuth 相关报错如果你连接的远程 MCP 服务需要 OAuth 认证而配置里没提供 token会报401或invalid_token。在mcp-servers.json的env里加上AUTH_TOKEN或者用headers字段传递{ mcpServers: { remote-tools: { url: https://your-mcp-server.example.com/mcp/sse, headers: { Authorization: Bearer ${MCP_AUTH_TOKEN} } } } }工具调用返回空结果模型没有触发工具调用或者工具名不匹配。检查Tool注解里的description是否清晰模型依赖描述来判断是否调用。另外确认mcpClient.getTools()返回的列表里确实包含你期望的工具可以在启动时打印工具数量。排查时建议按链路分段定位先确认 TaoToken 的模型调用是否通直接 curl API再确认 MCP 客户端是否连上服务看启动日志最后确认工具调用是否触发看 JSON-RPC 日志。把logging.level.org.springframework.aiDEBUG打开能看到完整的请求和响应内容。6. 长期编码与 Agent 场景的接入建议如果你打算把 Spring AI MCP 用在长期编码助手或 Agent 类项目里有几个实践建议可以参考。第一把 MCP 服务做成独立进程不要和主应用耦合。这样工具升级或重启不会影响主服务也方便单独调试。用 systemd 或 Docker 管理 MCP 服务进程配置健康检查。第二工具描述要写清楚。模型判断是否调用某个工具完全依赖description字段。比如“查询指定经纬度的实时天气”就比“天气工具”好得多。参数描述也要写全模型需要知道每个参数的含义和格式。第三控制工具数量。一次对话里挂载太多工具会增加模型的选择负担也容易触发误调用。按场景分组比如“数据查询类”和“文件操作类”分开配置按需加载。第四做好超时和重试。MCP 工具执行可能涉及外部 API网络抖动时要有兜底。在application.yml里设置合理的request-timeout代码层加一层重试逻辑避免单次失败导致整个对话中断。第五日志要留全。JSON-RPC 的请求和响应都记下来排查问题时能快速定位是模型没触发调用、还是工具执行失败、还是结果回传丢失。Spring AI 的 DEBUG 日志已经比较详细生产环境可以单独输出到文件。如果你需要更系统的接入文档和参数说明可以查阅 TaoToken 的接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 说明和示例。模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 可以用来快速验证模型可用性Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合高频编码场景。把 endpoint 统一到 TaoToken 之后你只需要维护一个 Key切换模型时改一下model字段就行不用再折腾多个平台的配置。
1. 为什么 Spring AI MCP 值得你花时间折腾如果你正在用 Spring Boot 做 AI 应用大概率遇到过这种场景模型需要查数据库、调天气接口、读本地文件每个工具都得单独写一套 Function Call 适配代码。工具一多接口风格不统一维护成本直线上升。MCPModel Context Protocol就是来解决这个问题的——它用一套基于 JSON-RPC 的标准协议把模型和外部工具的连接方式统一起来做到“即插即用”。Spring AI 对 MCP 的支持已经比较成熟通过 Spring Boot Starter 就能快速搭建 MCP 客户端和服务端。你可以把它理解成一个“工具总线”模型不需要知道每个工具的具体实现只需要按 MCP 规范发起调用剩下的路由、参数传递、结果返回都由协议层处理。这对 Java 开发者来说非常友好因为你可以继续用熟悉的 Spring 生态来管理依赖和配置。这篇文章面向的是已经了解 Spring Boot、想快速把 MCP 集成落地的开发者。我会从实际项目出发给出可复制的application.yml和 MCP 客户端配置片段重点演示如何把 endpoint 改到 TaoToken 统一 Key/API 通道并完成连通性验证。过程中会涉及 JSON-RPC 通信链路、多工具调用的配置要点以及常见的调用失败排查方法。读完你就能在自己的项目里跑通一条完整的 MCP 调用链路。2. TaoToken 前置准备统一 Key 与 API 通道在开始配置之前先把 TaoToken 的接入信息准备好。TaoToken 提供统一的 API 通道你只需要一个 Key 就能访问多种模型省去分别申请和管理多个平台账号的麻烦。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基础地址是 https://taotoken.net/api 。具体操作步骤第一步打开官网注册并登录进入控制台。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在这里你可以看到账户余额、调用统计等信息。第二步创建 API Key。进入 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 点击创建新 Key复制保存好。这个 Key 就是后面配置里的api-key值。第三步确认你要使用的模型 ID。TaoToken 支持多种模型你可以在模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 先测试一下模型是否可用确认模型名称后再写入配置。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频调用场景做了额度优化。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题可以对照查阅。这里要强调一点TaoToken 是合规的 API 统一通道你只需要按标准 HTTP 方式调用即可不需要任何额外网络配置。把 Base URL 设为https://taotoken.net/api带上你的 Key就能正常发起请求。3. 可复制配置application.yml 与 MCP 客户端片段这一节是核心直接给你可以复制到项目里的配置。假设你用的是 Spring Boot 3.x Spring AI 1.0.x先确认pom.xml里引入了 MCP 相关依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-client-spring-boot-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency然后是application.yml这里把模型 endpoint 指向 TaoTokenspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7 mcp: client: enabled: true name: spring-ai-mcp-client version: 1.0.0 request-timeout: 30s type: SYNC servers-configuration: classpath:/mcp-servers.json注意base-url后面不要加/v1TaoToken 的 API 路径已经处理好直接写https://taotoken.net/api即可。api-key建议用环境变量注入不要硬编码在文件里。接下来是src/main/resources/mcp-servers.json定义你要连接的 MCP 服务{ mcpServers: { weather: { command: java, args: [-jar, /opt/mcp/weather-server.jar], env: { API_KEY: ${TAOTOKEN_API_KEY} } }, database: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, /data/app.db] } } }如果你要连接远程 SSE 模式的 MCP 服务把command换成url{ mcpServers: { remote-tools: { url: https://your-mcp-server.example.com/mcp/sse } } }配置完成后Spring AI 会自动扫描mcp-servers.json并建立连接。你可以在启动日志里看到类似Registered MCP client: weather的输出说明客户端已经识别到服务。关于模型 ID 的填写如果你用的是 Claude 系列模型名要写全比如claude-3-5-sonnet-20241022。TaoToken 的模型列表可以在模型对话页面确认避免写错导致 404。4. 验证请求从 JSON-RPC 链路到成功结果配置写好后写一个简单的 Controller 来验证整条链路是否通。核心是注入ChatClient和McpClient然后发起一次带工具调用的对话RestController public class McpTestController { private final ChatClient chatClient; private final McpClient mcpClient; public McpTestController(ChatClient.Builder builder, McpClient mcpClient) { this.chatClient builder.build(); this.mcpClient mcpClient; } GetMapping(/test/mcp) public String testMcp(RequestParam String city) { String prompt 请调用天气工具查询 city 的天气并返回温度。; return chatClient.prompt() .user(prompt) .tools(mcpClient.getTools()) .call() .content(); } }启动项目后用 curl 发起请求curl http://localhost:8080/test/mcp?cityBeijing如果一切正常你会看到类似北京当前温度 25℃风速 2m/s的返回。这背后发生了什么Spring AI 把用户 prompt 发给 TaoToken 的模型 endpoint模型判断需要调用天气工具于是通过 JSON-RPC 向 MCP 客户端发起tools/call请求MCP 客户端路由到weather服务执行拿到结果后再回传给模型模型最终生成自然语言回复。你也可以直接测试 MCP 客户端本身不经过模型GetMapping(/test/tool) public String testTool() { McpToolCallback callback mcpClient.getToolCallbacks().get(0); return callback.call({\latitude\:\39.9042\,\longitude\:\116.4074\}); }这个接口会直接返回工具执行结果用来确认 MCP 服务端是否正常工作。如果这一步失败问题就在 MCP 服务端或 JSON-RPC 通信层而不是模型调用层。实测下来TaoToken 的响应速度比较稳定JSON-RPC 链路在同步模式下延迟主要来自工具执行本身。如果你需要高并发可以把type改成ASYNC配合request-timeout调整超时时间。5. 常见报错排查401、local proxy failed、reading choices集成过程中最容易踩的坑集中在几个典型报错上这里逐一对照排查。401 Unauthorized这个最常见说明 API Key 没传对。检查application.yml里的api-key是否读到了环境变量可以在启动时打印System.getenv(TAOTOKEN_API_KEY)确认。另外注意 Key 有没有多余空格复制时容易带上换行符。如果用的是 TaoToken 的 Key确认它没有过期或被删除可以在 API Keys 页面重新生成一个。local proxy failed / connection refused这个报错通常出现在 MCP 客户端连接本地 stdio 服务时。检查mcp-servers.json里的command路径是否正确args里的 jar 包路径是否存在。如果是npx命令确认本机 Node.js 版本是否支持。还有一种情况是 MCP 服务启动超时把request-timeout从 30s 调到 60s 试试。reading choices 报错这个一般出现在模型返回结构解析阶段说明 TaoToken 返回的 JSON 格式和 Spring AI 预期的 OpenAI 格式有差异。检查base-url是否写成了https://taotoken.net/api/v1多写/v1会导致路径拼接错误。正确的写法就是https://taotoken.net/api。另外确认model名称是否在 TaoToken 支持列表里写错模型名有时会返回非标准错误结构。OAuth 相关报错如果你连接的远程 MCP 服务需要 OAuth 认证而配置里没提供 token会报401或invalid_token。在mcp-servers.json的env里加上AUTH_TOKEN或者用headers字段传递{ mcpServers: { remote-tools: { url: https://your-mcp-server.example.com/mcp/sse, headers: { Authorization: Bearer ${MCP_AUTH_TOKEN} } } } }工具调用返回空结果模型没有触发工具调用或者工具名不匹配。检查Tool注解里的description是否清晰模型依赖描述来判断是否调用。另外确认mcpClient.getTools()返回的列表里确实包含你期望的工具可以在启动时打印工具数量。排查时建议按链路分段定位先确认 TaoToken 的模型调用是否通直接 curl API再确认 MCP 客户端是否连上服务看启动日志最后确认工具调用是否触发看 JSON-RPC 日志。把logging.level.org.springframework.aiDEBUG打开能看到完整的请求和响应内容。6. 长期编码与 Agent 场景的接入建议如果你打算把 Spring AI MCP 用在长期编码助手或 Agent 类项目里有几个实践建议可以参考。第一把 MCP 服务做成独立进程不要和主应用耦合。这样工具升级或重启不会影响主服务也方便单独调试。用 systemd 或 Docker 管理 MCP 服务进程配置健康检查。第二工具描述要写清楚。模型判断是否调用某个工具完全依赖description字段。比如“查询指定经纬度的实时天气”就比“天气工具”好得多。参数描述也要写全模型需要知道每个参数的含义和格式。第三控制工具数量。一次对话里挂载太多工具会增加模型的选择负担也容易触发误调用。按场景分组比如“数据查询类”和“文件操作类”分开配置按需加载。第四做好超时和重试。MCP 工具执行可能涉及外部 API网络抖动时要有兜底。在application.yml里设置合理的request-timeout代码层加一层重试逻辑避免单次失败导致整个对话中断。第五日志要留全。JSON-RPC 的请求和响应都记下来排查问题时能快速定位是模型没触发调用、还是工具执行失败、还是结果回传丢失。Spring AI 的 DEBUG 日志已经比较详细生产环境可以单独输出到文件。如果你需要更系统的接入文档和参数说明可以查阅 TaoToken 的接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的 API 说明和示例。模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 可以用来快速验证模型可用性Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合高频编码场景。把 endpoint 统一到 TaoToken 之后你只需要维护一个 Key切换模型时改一下model字段就行不用再折腾多个平台的配置。
