1. 从一次真实踩坑说起多工具接入为什么让人头大如果你正在用 Spring Boot 写 AI 应用大概率会遇到这样一个场景项目里既要接高德地图查路线又要接别的工具查天气、查数据库每个工具背后都是一套独立的 Key、独立的通道、独立的配置。刚开始只有一两个还好等到第五六个工具接进来application.yml里全是各种api-key、base-url改一个环境变量要翻半天本地跑通了换台机器又挂。Spring AI 的 MCPModel Context Protocol客户端启动器本质上就是来解决「工具接入标准化」这件事的。它让你用统一的协议去连接不同的 MCP Server把工具执行交给 Spring AI 的ChatClient框架。但 MCP 只解决了「怎么连」没解决「Key 和通道怎么统一管」。这就是我这篇要讲的重点用 TaoToken 做统一 Key 入口配合 Spring AI MCP 客户端把高德地图这类工具接进来让配置收敛到一处。这篇适合谁有 Java 17 基础、写过 Spring Boot、想快速跑通 MCP 客户端链路的同学。我会给出application.yml和mcp-servers-config.json的骨架演示连接高德地图 MCP 服务后的调用验证动作最后把常见的报错一个个拆开讲。全程可跟做不需要你提前理解 MCP 协议的全部细节。2. TaoToken 前置把分散的 Key 收成一个入口在讲配置之前先说清楚 TaoToken 在这里扮演什么角色。你可以把它理解成一个统一的模型与工具调用入口原本你要为每个模型供应商、每个工具单独申请 Key、单独配base-url现在通过 TaoToken 拿一个 Key就能走同一个 API 地址去调用不同的模型和工具通道。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址是https://taotoken.net/api 注意这个不加 UTM 参数配置里直接填这个。具体到 Spring AI 项目里你需要做两件事第一去控制台创建一个 API Key。地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完复制出来后面填到环境变量里。第二如果你要长期跑编码类或 Agent 类任务可以看下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。建议先把文档扫一遍里面把模型对话、工具调用的参数都列清楚了。注意TaoToken 是合规的 API 聚合入口配置时只填官方给的地址不要自己拼别的域名。拿到 Key 之后你的 Spring AI 项目里模型这一侧的配置就统一了spring.ai.openai.api-key填 TaoToken 的 Keyspring.ai.openai.base-url填https://taotoken.net/api。工具那一侧比如高德地图 MCP Server的 Key 仍然由高德自己管但模型通道已经收敛了。3. 可复制配置application.yml 与 mcp-servers-config.json 骨架先看依赖。pom.xml里至少要有这两个dependencies 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然后是application.yml。这里我把模型通道指向 TaoToken工具通道用 STDIO 方式连高德地图 MCP Serverspring: application: name: mcp-amap-demo main: web-application-type: none ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini mcp: client: stdio: connections: amap-maps-mcp-server: command: npx args: - -y - amap/amap-maps-mcp-server env: AMAP_MAPS_API_KEY: ${AMAP_MAPS_API_KEY}几个关键点解释一下。web-application-type: none是因为这是个命令行应用不需要起 Web 容器。stdio.connections下面每一个命名节点就是一个 MCP Server 连接amap-maps-mcp-server是连接名你可以随便起但后面引用要对得上。command和args是启动这个 MCP Server 的方式高德官方提供的是 npm 包所以用npx -y直接拉起来。如果你不想把连接写在application.yml里也可以用 Claude Desktop 格式的外部 JSON。在application.yml里加一行spring: ai: mcp: client: stdio: servers-configuration: classpath:/mcp-servers-config.json然后src/main/resources/mcp-servers-config.json内容如下{ mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: ${AMAP_MAPS_API_KEY} } } } }两种方式选一种就行别同时配否则可能出现连接重复。我个人更推荐 JSON 方式因为换工具的时候只改一个文件application.yml保持干净。环境变量在启动前导出export TAOTOKEN_API_KEY你的TaoToken密钥 export AMAP_MAPS_API_KEY你的高德地图密钥高德地图的 Key 去高德开放平台的 MCP Server 创建页申请这里不展开。4. 验证请求跑通一次真实调用配置写完先构建./mvnw clean install然后运行通过-Dai.user.input传入问题java -Dai.user.input从北京西站到首都机场怎么走 \ -jar target/mcp-amap-demo-0.0.1-SNAPSHOT.jar应用启动后Spring AI 会做这几件事读取stdio.connections配置为每个连接创建一个 MCP 客户端通过npx拉起高德地图 MCP Server 进程把 MCP Server 暴露的工具注册到ChatClient的工具执行框架里把你的问题发给模型模型决定调用哪个工具Spring AI 负责执行并把结果回传。如果一切正常你会在控制台看到类似这样的输出User: 从北京西站到首都机场怎么走 Assistant: 根据高德地图的路线规划从北京西站到首都机场……这里有个细节值得注意模型本身并不知道怎么调高德地图它只是看到了一组工具描述tool schema然后决定「这个问题应该用 maps_direction_driving 这个工具」。真正执行调用的是 Spring AI 的 MCP 客户端它把参数传给高德 MCP Server拿到结果再交回模型组织语言。这就是 MCP 的价值——工具和模型解耦。如果你想单独验证模型通道是否通可以用模型对话页面直接测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 发一句话看有没有正常返回。这一步能帮你快速区分是模型通道的问题还是 MCP 工具的问题。5. 本篇常见错排查5.1 npx 找不到或 MCP Server 起不来报错长这样Cannot run program npx: error2, No such file or directory这是环境里没装 Node.js或者npx不在 PATH 里。先确认node -v npx -v两个都有版本号才行。Windows 上如果用的是npx.cmd在application.yml里要把command改成npx.cmdJSON 配置同理。我试过在 Mac 上直接写npx没问题换到 Windows 就得多加.cmd后缀。5.2 高德 Key 没生效工具调用返回鉴权失败现象是模型能回复但一涉及地图就报错类似INVALID_USER_KEY。检查两点一是AMAP_MAPS_API_KEY环境变量有没有真的导出可以用echo $AMAP_MAPS_API_KEY确认二是高德开放平台里这个 Key 有没有绑定 MCP Server 服务Key 是按服务类型授权的不是随便一个 Key 都能调 MCP。5.3 模型通道 401 或 base-url 配错如果你看到401 Unauthorized先确认TAOTOKEN_API_KEY有没有填对以及base-url是不是https://taotoken.net/api。注意不要写成带/v1的路径Spring AI 的 OpenAI starter 会自己拼。如果还是不通去 API Keys 页面重新生成一个 Key 试试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。5.4 工具注册了但模型不调用有时候配置都对模型就是不调工具直接凭记忆回答。这通常是因为模型能力不够或者工具描述没被正确加载。换一个支持 function calling 的模型比如gpt-4o-mini或更强的。另外确认spring-ai-starter-mcp-client的版本和 Spring AI 主版本一致版本错配会导致工具注册静默失败。5.5 应用启动后立刻退出因为web-application-type: none且没有常驻线程命令行应用执行完就退。这是预期行为。如果你想让它交互式循环需要自己写一个CommandLineRunner读取输入。参考文档里有完整示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 把链路固定下来后续怎么扩展跑通之后你会发现这套结构的扩展性很好。想加一个新工具比如天气 MCP Server只需要在mcp-servers-config.json里加一个节点{ mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: ${AMAP_MAPS_API_KEY} } }, weather: { command: npx, args: [-y, some-weather-mcp-server], env: { WEATHER_API_KEY: ${WEATHER_API_KEY} } } } }模型通道那边完全不用动TaoToken 的 Key 和 base-url 保持一份。这就是统一 Key 入口的好处工具在变模型通道不变。如果你后面要做更复杂的 Agent 编排或者需要长时间跑编码任务可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它针对高频调用场景做了优化比按量计费更适合持续跑的任务。最后留一个我自己的习惯每次改完 MCP 配置先用一个最简单的问题验证比如「北京今天天气怎么样」确认工具链路通了再去调复杂的业务逻辑。这样出问题的时候你能快速定位是配置层还是业务层。