1. 从一次真实踩坑说起Spring AI Alibaba 接 MCP 公开服务到底难在哪如果你正在用 Spring AI Alibaba 做 Agent又想让它调用 MCP 市场里的公开服务大概率会遇到三个卡点一是 MCP 服务的鉴权 Key 分散在各家平台高德一个、天气一个、搜索又一个管理起来很碎二是 Spring AI Alibaba 的 MCP 客户端配置项在版本迭代中改过名字网上抄来的application.yml经常对不上三是模型侧和工具侧的 Key 混在一起报 401 的时候根本分不清是模型没通还是 MCP 服务没通。这篇就围绕「Spring AI Alibaba 通过 MCP 协议调用 MCP 市场公开服务」这条完整链路来写用一个真实可复现的例子——高德地图 MCP 服务——把配置、代码、验证、排错全部走一遍。同时把模型鉴权这一层统一收到 TaoToken 的 Key 上这样你只需要维护一套 API 通道MCP 服务本身的 Key比如高德的AMAP_MAPS_API_KEY单独放职责清晰出问题好定位。适合谁看有 Spring Boot 基础、想快速把 MCP 公开服务接进自己 Agent 的后端同学已经在用 Spring AI Alibaba 但 MCP 一直没跑通的以及想搞清楚「MCP 客户端配置到底该写哪些字段」的人。读完你能拿到一份可直接复制的application.yml、一份mcp-servers-config.json以及一次真实调用的返回结果对照。先说清楚 MCP 是什么避免概念糊着。MCPModel Context Protocol本质是一套让模型和外部工具对话的约定工具方按协议暴露自己的能力比如「查天气」「查路线」客户端按协议去发现和调用。MCP 市场就是这些公开服务的集合地类似工具的「应用商店」。Spring AI Alibaba 在这里扮演的是 MCP 客户端 Agent 编排者的角色它负责把 MCP 服务暴露的工具注册成ToolCallback再交给大模型决定什么时候调。2. 前置准备TaoToken 统一 Key 与 MCP 服务 Key 的分工在动手写配置前先把「两把 Key」的分工理清楚这是后面排错的基础。第一把是模型侧的 Key。Spring AI Alibaba 默认走 DashScope通义千问但你可以把模型通道换成兼容 OpenAI 协议的服务。这里用 TaoToken 作为统一入口好处是模型对话、Coding Plan、API Keys 都在一个控制台里管Base URL 和 Key 一套搞定不用在多个平台之间来回切。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions调用方式Spring AI Alibaba 里通过base-url和api-key两个字段就能接上。第二把是 MCP 服务自己的 Key。比如高德地图 MCP 服务需要AMAP_MAPS_API_KEY这个必须去高德开放平台申请跟模型 Key 完全是两回事。很多人第一次配的时候把这两个搞混结果模型通了但工具调用报鉴权失败或者反过来。TaoToken 在这里的角色是「模型侧统一通道」不是 MCP 服务的中转。MCP 服务仍然由它自己的进程比如npx amap/amap-maps-mcp-server拉起走 stdio 通信Spring AI Alibaba 作为客户端去连它。这个边界一定要清楚否则你会以为配了 TaoToken 的 Key 就能调高德那是不对的。具体操作上你可以先去 TaoToken 控制台拿 Key进入 API Keys 页面创建一个复制出来备用。模型选哪个、用哪个通道可以在模型对话页面先试一下确认 Key 有效再往项目里塞。如果你后面要做长期编码或 Agent 任务Coding Plan 那条线也可以顺带了解它和按量调用的 Key 是分开管理的。高德这边的 Key 申请流程不复杂登录高德开放平台创建一个应用服务平台选「Web 服务」提交后就能拿到 API-Key。注意一定要选 Web 服务类型选错了调 MCP 会失败。拿到后先存好下一步配置里要替换。MCP 市场里找服务可以用 mcp.so 这类聚合站搜「amap-maps」就能找到高德地图 MCP 服务的详情页页面上会给出一段「服务器配置 JSON」这段 JSON 就是我们要放进项目的核心配置。重点看env里的AMAP_MAPS_API_KEY字段把它替换成你自己的 Key。3. 可复制配置application.yml 与 mcp-servers-config.json 全量片段这一节是全文的核心配置写对了后面基本就顺了。分两个文件一个是 MCP 服务的描述文件mcp-servers-config.json一个是 Spring Boot 的application.yml。先建mcp-servers-config.json放在src/main/resources/下。内容如下注意把AMAP_MAPS_API_KEY换成你自己的高德 Key{ mcpServers: { amap-maps: { command: npx, args: [ -y, amap/amap-maps-mcp-server ], env: { AMAP_MAPS_API_KEY: 你的高德Key } } } }这段 JSON 的含义mcpServers下每个键是一个 MCP 服务的名字这里叫amap-mapscommand是启动这个服务的命令args是参数env是传给这个进程的环境变量。Spring AI Alibaba 启动时会读取这个文件按里面的定义把 MCP 服务进程拉起来并通过 stdio 跟它通信。然后是application.yml。这里同时配了模型通道走 TaoToken和 MCP 客户端spring: application: name: spring-ai-alibaba-mcp-demo ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini mcp: client: type: async request-timeout: 30s toolcallback: enabled: true stdio: servers-configuration: classpath:/mcp-servers-config.json几个关键点逐个说。spring.ai.openai.base-url指向 TaoToken 的 API 地址api-key用环境变量注入别硬编码在文件里。model按你实际能用的填这里只是示例。MCP 部分type: async表示异步客户端request-timeout建议给到 30s因为 MCP 服务首次启动要下载 npm 包10s 经常不够。toolcallback.enabled: true是让 Spring AI Alibaba 自动把 MCP 工具注册成ToolCallback。stdio.servers-configuration指向刚才那个 JSON 文件用classpath:前缀表示从资源目录读。如果你用的是 DashScope 而不是 OpenAI 兼容通道把spring.ai.openai那段换成spring.ai.dashscopeapi-key填 DashScope 的 Key 即可。但既然这篇主打 TaoToken 统一 Key建议就用 OpenAI 兼容通道Base URL 和 Key 一套走天下。依赖方面pom.xml里至少要有 Spring AI Alibaba 的 starter 和 MCP 客户端相关依赖。版本上注意 Spring AI Alibaba 和 Spring AI 的对应关系版本错配是toolcallback配置不生效的常见原因。建议锁定一个官方文档里标注兼容的组合别自己乱升。配置写完后启动项目。如果控制台看到 MCP 服务进程被拉起、工具列表被打印出来说明配置这层通了。如果没通先别急着写业务代码直接跳到第 5 节排错。4. 验证请求一次真实公开服务调用的返回结果对照配置通了之后写一个测试接口来验证整条链路。核心逻辑是拿到 MCP 注册进来的ToolCallback构建一个ReactAgent把工具绑上去然后问一个需要调用工具的问题。GetMapping(/mcpTest) public String mcpTest() throws GraphRunnerException { ChatModel chatModel getChatModel(); ToolCallback[] toolCallbacks toolCallbackProvider.getToolCallbacks(); System.out.println( MCP Tools ); System.out.println(JSON.toJSONString(toolCallbacks)); ReactAgent agent ReactAgent.builder() .name(amap_agent) .model(chatModel) .description(你是一个地图与天气查询助手) .saver(new MemorySaver()) .toolCallbackProviders(toolCallbackProvider) .build(); RunnableConfig config RunnableConfig.builder() .threadId(session-001) .build(); FluxNodeOutput stream agent.stream(上海未来天气怎么样, config); StringBuilder answer new StringBuilder(); stream.doOnNext(output - { if (output.node().equals(_AGENT_MODEL_)) { answer.append(((StreamingOutput?) output).message().getText()); } else if (output.node().equals(_AGENT_TOOL_)) { answer.append(\nTool Call: ) .append(((ToolResponseMessage) ((StreamingOutput?) output).message()) .getResponses().get(0)) .append(\n); } }).doOnComplete(() - System.out.println(answer)) .doOnError(e - System.err.println(Stream Error: e.getMessage())) .blockLast(); return answer.toString(); }启动项目访问http://localhost:8080/mcpTest。预期能看到两段输出。第一段是工具列表。控制台会打印出从 MCP 服务发现的所有工具高德地图 MCP 一般会暴露maps_weather、maps_geo、maps_direction_driving等。看到这些名字说明 MCP 服务被正确拉起、工具被正确注册。第二段是模型回答。因为问的是「上海未来天气怎么样」模型会先决定调用maps_weather工具工具返回天气数据模型再基于数据组织自然语言回答。流式输出里会先出现Tool Call:那段然后是模型整理后的天气描述。返回结果对照上工具返回的是结构化 JSON城市、日期、天气、温度等字段模型输出的是口语化总结两者能对上就说明链路完整。如果工具列表是空的或者模型直接回答「我无法查询天气」说明工具没注册上回到第 3 节检查toolcallback.enabled和 JSON 路径。如果工具被调用了但返回鉴权错误那是高德 Key 的问题跟 TaoToken 无关。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把几个高频报错逐个拆开对照真实日志说清楚原因和解法。401 Unauthorized模型侧。日志里如果出现401且堆栈指向 chat 请求基本是模型 Key 或 Base URL 的问题。检查spring.ai.openai.api-key是否真的注入成功环境变量名别写错base-url是否是https://taotoken.net/api。注意有些版本要求 base-url 带/v1有些不带以你用的 Spring AI 版本为准。如果 Key 是从 TaoToken 控制台复制的确认没多复制空格。local proxy failed / connection refused。这个通常出现在 MCP 服务进程没起来的时候。npx首次执行要联网下载包如果网络环境导致下载失败进程起不来客户端连接就会报 proxy failed。解法先在终端手动跑一遍npx -y amap/amap-maps-mcp-server确认能启动、能看到它等待 stdio 输入再回到项目里启动。另外request-timeout给足别用默认的短超时。reading choices / choices 字段解析失败。这个报错说明模型返回的 JSON 结构不符合 OpenAI 兼容格式常见于 Base URL 指错了地方或者模型名填了一个该通道不支持的。检查model字段是不是 TaoToken 通道里可用的模型 ID别填一个不存在的名字。如果换了模型就好那就是模型 ID 的问题。OAuth / 鉴权跳转相关报错。如果你接的 MCP 服务是需要 OAuth 授权的不是所有公开服务都免鉴权而配置里只写了 stdio env就会在调用时被要求走授权流程。高德这个例子用的是 API-Key 模式不涉及 OAuth。如果你换成别的服务遇到 OAuth 报错要么换一个 API-Key 模式的服务要么按该服务的文档补授权配置。别硬套本文的 JSON。工具列表为空但没报错。这种最隐蔽。检查servers-configuration的路径前缀classpath:/mcp-servers-config.json前面那个斜杠别丢。再检查 JSON 文件是否真的在resources根目录下别放进了子目录。还有toolcallback.enabled必须是true。排错时有个通用思路把「模型通道」和「MCP 通道」分开验证。先用一个不涉及工具的普通对话接口确认模型通再用工具列表打印确认 MCP 通两个都通了再合起来测 Agent。这样报错定位快很多。6. 把 Key 和通道收拢后续接入与验证的入口跑通高德这个例子后你会发现真正需要维护的东西不多一份 MCP 服务描述 JSON、一段application.yml、一个模型通道的 Key。MCP 市场里其他公开服务大多也是同样的套路——找到它的配置 JSON替换掉里面的 Key加进mcpServers重启即可。多个服务可以并列写在同一个 JSON 里Spring AI Alibaba 会把它们的工具一起注册。模型侧统一用 TaoToken 的 Key 之后你换模型、加通道、看用量都在一个控制台里不用每接一个服务就重新配一遍模型鉴权。需要新 Key 或管理已有 Key去 API Keys 页面操作想先验证某个模型能不能用模型对话页面直接试要做长期编码或 Agent 类任务Coding Plan 那条线可以单独看。接入文档里有各语言和框架的配置示例Spring AI Alibaba 的字段对照也能在里面找到。最后留一个实操建议把mcp-servers-config.json里的 Key 也用环境变量占位别直接写明文。Spring AI Alibaba 读取 JSON 时支持${ENV_NAME}这种占位符取决于版本或者你在启动脚本里做替换。这样 JSON 文件可以进版本库Key 留在本地环境团队协作时不会互相覆盖。