1. 为什么 Spring AI 接 MCP 服务总在配置环节卡住如果你正在用 Spring AI 构建 MCP 服务大概率会遇到一个很具体的场景本地把 Spring Boot 工程跑起来了工具方法也写好了但模型侧就是调不通。报错五花八门有的是 401有的是连接超时有的是模型名对不上。问题往往不在业务代码而在模型接入这一层的配置骨架没搭对。MCP 服务在 Spring AI 里的定位是把本地工具能力暴露给模型调用。它本身不生产模型能力而是负责把请求转发到模型服务、再把模型返回的工具调用意图解析成实际方法执行。所以模型接入配置是整个链路的地基。地基不稳后面工具注册、参数映射、结果回传全是空中楼阁。这篇内容面向的是本地开发联调场景。我会给出可复制的 settings.json 与 config.toml 骨架说明 TaoToken 统一 Key 和 API 通道怎么接进去最后用一个 MCP 服务启动加工具调用的完整动作验证链路。适合已经在写 Spring AI 工程、但模型接入还没跑通的开发者。读完你能拿到一套能直接改改就用的配置模板以及一次可复现的验证流程。2. TaoToken 在 Spring AI MCP 链路里的位置TaoToken 在这里扮演的是统一模型接入层的角色。你可以把它理解成一个 API 通道Spring AI 的 MCP 服务不需要分别对接多个模型厂商的地址和密钥而是统一走一个 Key、一个 Base URL。这样在本地联调时切换模型只需要改配置里的模型名不用动代码。对 MCP 服务来说这个设计的好处很直接。MCP 的核心工作是工具调用编排模型接入越简单编排逻辑越干净。你不需要在 Spring 配置里维护一堆不同厂商的 Bean也不需要为每个模型写单独的 Client 初始化代码。接入前你需要准备两样东西一个可用的 API Key以及确认 Base URL 指向https://taotoken.net/api。Key 的获取在控制台的 API Keys 页面完成登录后新建一个 Key 即可。如果你还没注册从官网入口进控制台就行。注意Base URL 填https://taotoken.net/api不要带多余路径。Spring AI 的 OpenAI 兼容客户端会自动拼接/v1/chat/completions这类后缀手动加路径反而会 404。模型对话能力可以先在模型对话页面验证一下 Key 是否可用确认能正常返回再进工程配置。这一步能帮你排除掉大部分 Key 本身的问题。3. 可复制的 settings.json 与 config.toml 骨架Spring AI 工程里模型接入配置通常分两层一层是应用级配置用application.yml或application.properties另一层是 MCP 服务自身的描述文件常见的是settings.json和config.toml。下面给出可直接复制的骨架。3.1 settings.json 骨架这个文件描述 MCP 服务的基本信息和模型接入参数。放在工程src/main/resources下。{ mcpServers: { spring-ai-mcp-local: { command: java, args: [ -jar, target/mcp-service-0.0.1-SNAPSHOT.jar ], env: { TAOTOKEN_API_KEY: sk-你的Key, TAOTOKEN_BASE_URL: https://taotoken.net/api, SPRING_PROFILES_ACTIVE: local } } } }这里的关键是env段。把 Key 和 Base URL 通过环境变量注入而不是硬编码在 Java 代码里。本地联调时改 Key 只需要改这个文件不用重新编译。3.2 config.toml 骨架如果你的 MCP 客户端或工具链读取 TOML 格式用下面这份。字段和上面的 JSON 一一对应。[mcp_servers.spring-ai-mcp-local] command java args [-jar, target/mcp-service-0.0.1-SNAPSHOT.jar] [mcp_servers.spring-ai-mcp-local.env] TAOTOKEN_API_KEY sk-你的Key TAOTOKEN_BASE_URL https://taotoken.net/api SPRING_PROFILES_ACTIVE local3.3 Spring 侧 application.yml 对接MCP 服务启动后Spring AI 需要知道去哪里调模型。在application.yml里配置 OpenAI 兼容客户端。spring: ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: ${TAOTOKEN_BASE_URL} chat: options: model: gpt-4o-mini temperature: 0.7 embedding: options: model: text-embedding-3-small mcp: server: name: spring-ai-mcp-local version: 0.0.1 transport: stdioapi-key和base-url都从环境变量读和 settings.json 里的注入保持一致。model字段按你实际要用的模型名填本地联调建议先用小模型跑通链路再换大模型。3.4 依赖配置pom.xml里需要引入 Spring AI 的 OpenAI starter 和 MCP 相关依赖。dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0-M4/version /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-spring-boot-starter/artifactId version1.0.0-M4/version /dependency /dependencies版本号按你工程实际用的 Spring AI 版本对齐。M4 之后的版本对 MCP 支持更完整建议不要用太老的里程碑版本。4. 一次 MCP 服务启动与工具调用的验证配置写完接下来是验证。这一步的目标是确认三件事MCP 服务能启动、模型能通过 TaoToken 通道调通、工具调用能被正确触发。4.1 定义工具方法先写一个最简单的工具用来验证调用链路。Component public class WeatherTools { Tool(description 查询指定城市的天气) public String getWeather(ToolParam(description 城市名称) String city) { return city 今天晴气温 22 度; } }Tool注解把方法注册为 MCP 工具ToolParam描述参数。模型会根据 description 决定是否调用这个工具。4.2 注册工具并启动服务在主配置类里把工具注册进 MCP 服务。Configuration public class McpConfig { Bean public ToolCallbackProvider weatherToolProvider(WeatherTools weatherTools) { return MethodToolCallbackProvider.builder() .toolObjects(weatherTools) .build(); } }启动命令export TAOTOKEN_API_KEYsk-你的Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api mvn spring-boot:run看到Started McpApplication日志说明服务起来了。4.3 触发一次工具调用用 curl 模拟一次模型请求验证工具调用是否被触发。curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [ {role: user, content: 北京天气怎么样} ], tools: [ { type: function, function: { name: getWeather, description: 查询指定城市的天气, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } } ] }预期返回里会包含tool_calls字段function.name是getWeatherarguments里是{city:北京}。这说明模型正确识别了工具并生成了调用参数。MCP 服务侧收到这个意图后会执行getWeather方法并把结果回传。4.4 验证结果对照检查项预期结果常见异常服务启动日志出现 Started McpApplication端口占用、依赖缺失Key 鉴权请求返回 200401 表示 Key 无效模型响应返回 tool_calls 字段模型名错误返回 404工具参数arguments 含 city 字段description 不清晰导致不调用5. 本篇常见错排查配置跑不通时按下面顺序排查能覆盖九成以上的问题。401 UnauthorizedKey 没注入成功。检查echo $TAOTOKEN_API_KEY是否有值settings.json 里的 env 是否被正确读取。Spring 侧确认api-key字段确实读到了环境变量而不是空字符串。404 Not FoundBase URL 写错了。确认是https://taotoken.net/api没有多余斜杠或路径。Spring AI 会自动拼/v1/chat/completions手动加/v1会变成/v1/v1/...。模型不调用工具Tool的 description 太模糊。模型靠 description 判断是否调用写清楚工具用途和参数含义。比如「查询指定城市的天气」比「天气工具」有效得多。连接超时本地网络到 API 通道不通。先用 curl 直接请求一次确认网络层没问题再查工程配置。如果 curl 通但工程不通检查 Spring 的base-url是否被其他配置覆盖。工具调用后无结果回传MCP 服务的 transport 配置不对。本地联调用stdio确认 settings.json 里的 command 和 args 能正确拉起 jar 包。jar 路径写相对路径时注意工作目录。模型名报错application.yml里的 model 字段和实际请求的模型名不一致。本地联调先用一个确认可用的模型名跑通再换。6. 接入配置跑通后的下一步配置骨架跑通之后你手里就有了一套可复用的模型接入层。接下来可以做的事很明确把更多工具方法注册进 MCP 服务让模型能调用的能力从天气查询扩展到实际业务。每加一个工具只需要写一个带Tool注解的方法配置层不用动。如果你打算长期在本地做编码和 Agent 联调Coding Plan 提供了更稳定的调用额度适合反复调试工具调用链路的场景。需要管理多个 Key 或查看调用量时控制台和 API Keys 页面能直接操作。接入文档里有更完整的参数说明和错误码对照遇到本文没覆盖的报错可以去查。本地联调阶段建议把日志级别调到 DEBUGSpring AI 会打印完整的请求和响应体排查工具调用问题时非常有用。等链路稳定了再调回 INFO避免日志刷屏。