企业官网建设流程全解析

1. 为什么 MCP 市场服务一多，API-Key 就开始失控

Spring AI Alibaba 接入 MCP 之后，最直观的变化是：你不再需要为每个外部能力单独写一套 SDK 适配代码。高德地图、天气、搜索、数据库查询，只要对方提供了 MCP Server，理论上都能通过统一的ToolCallbackProvider挂到 Agent 上。但真正开始接第二个、第三个 MCP 服务时，问题往往不在协议层，而在配置层——每个服务都有自己的env字段，每个env里都塞着一个独立的 API-Key。

我见过最常见的写法是：mcp-servers-config.json里高德一个 Key、天气一个 Key、某个内部工具再一个 Key，然后application.yml里还躺着 DashScope 的 Key。项目一旦要换环境、做多人协作、或者把配置提交到仓库，Key 的散落就成了隐患。更麻烦的是，Spring AI Alibaba 的 MCP 客户端配置目前主要围绕stdio和servers-configuration展开，Key 的注入点天然分散在 JSON 文件里，想统一管理并不直观。

这篇要解决的就是这件事：以高德地图 MCP 服务为例，把 MCP 市场公开服务的调用链路跑通，同时用 TaoToken 的统一 Key 思路，把多服务 Key 的注入收敛到一个可复制的配置骨架里。适合已经在用 Spring AI Alibaba、准备接第一个或第二个 MCP 公开服务的同学。核心检索词先摆出来：Spring AI Alibaba、MCP、高德地图、API-Key、application.yml，这五个词会贯穿全文。

需要提前说明的是，MCP 市场里的公开服务本质上是第三方能力封装，调用它们仍然需要遵守对应平台的使用条款。高德地图的 Key 要在高德开放平台申请，TaoToken 的 Key 用于统一管理模型侧调用，两者职责不同，不要混为一谈。下面按「前置准备 → 配置骨架 → 代码验证 → 排障」的顺序展开，每一步都给可复制的片段。

2. TaoToken 前置：统一 Key 的定位与准备

在讲配置之前，先把 TaoToken 在这个链路里的角色说清楚。Spring AI Alibaba 的 Agent 需要一个大模型来驱动推理和工具调用决策，这个模型可以是 DashScope，也可以是其他兼容 OpenAI 协议的服务。TaoToken 在这里承担的是模型侧的统一入口：你申请一个 Key，就可以在application.yml里通过base-url和api-key指向它，后续换模型、换环境时只改这一处。

TaoToken 的官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数，配置里填的就是这个。如果你还没申请 Key，可以先去控制台创建，入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，创建完成后在 API Keys 页面复制，页面地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

这里要区分两个 Key：

两者不能互相替代。TaoToken 的 Key 管的是「谁来思考」，高德的 Key 管的是「地图数据从哪来」。把这两个 Key 分开管理，是后面配置骨架能保持清晰的前提。如果你后续还要接更多 MCP 服务，每个服务自己的 Key 仍然放在各自的env里，但模型侧的 Key 始终只有 TaoToken 这一个。

关于模型选择，TaoToken 支持在模型对话页面直接测试连通性，入口是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。建议在写代码之前，先在对话页面确认 Key 可用、模型能正常返回，避免把模型侧的问题和 MCP 侧的问题混在一起排查。如果你打算长期做编码类 Agent，也可以了解 Coding Plan，入口是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它更适合高频调用场景。

3. 可复制配置：application.yml 与 MCP 服务注册骨架

这一节是全文的核心，目标是给出一份可以直接抄的配置骨架。先看目录结构，建议这样组织：

src/main/resources/ ├── application.yml └── mcp-servers-config.json

mcp-servers-config.json负责描述 MCP Server 的启动方式和环境变量，application.yml负责告诉 Spring AI Alibaba 去哪里读这个文件、以及模型侧怎么连。先写 JSON：

{ "mcpServers": { "amap-maps": { "command": "npx", "args": [ "-y", "@amap/amap-maps-mcp-server" ], "env": { "AMAP_MAPS_API_KEY": "${AMAP_MAPS_API_KEY}" } } } }

注意这里我把AMAP_MAPS_API_KEY写成了占位符形式，而不是直接把 Key 硬编码进去。这样做的目的是让 JSON 文件可以安全地提交到仓库，真正的 Key 通过环境变量或application.yml注入。如果你本地调试图省事，也可以先直接填 Key，但提交前一定要改回来。

接下来是application.yml的骨架：

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: 10s toolcallback: enabled: true stdio: servers-configuration: classpath:/mcp-servers-config.json amap: maps: api-key: ${AMAP_MAPS_API_KEY}

这份配置里有几个点需要展开。第一，spring.ai.openai.base-url指向 TaoToken 的 API 地址，api-key用${TAOTOKEN_API_KEY}从环境变量读取，这样本地、测试、生产可以各用各的 Key，配置文件本身不变。第二，spring.ai.mcp.client.stdio.servers-configuration指向 classpath 下的 JSON 文件，Spring AI Alibaba 启动时会读取它并拉起对应的 MCP Server 进程。第三，request-timeout设成 10s 是个保守值，高德地图的天气、地理编码类接口通常够用，如果遇到超时可以调到 20s。

关于环境变量的设置，Linux/macOS 下可以这样：

export TAOTOKEN_API_KEY="你的TaoTokenKey" export AMAP_MAPS_API_KEY="你的高德Web服务Key"

Windows PowerShell 下：

$env:TAOTOKEN_API_KEY="你的TaoTokenKey" $env:AMAP_MAPS_API_KEY="你的高德Web服务Key"

如果你用的是 IDEA，也可以在 Run Configuration 的 Environment variables 里填。这里有个容易踩的坑：mcp-servers-config.json里的${AMAP_MAPS_API_KEY}是 Spring 的占位符解析，不是 shell 的变量展开，所以它依赖 Spring 环境里能读到这个属性。上面application.yml里特意加了amap.maps.api-key: ${AMAP_MAPS_API_KEY}，就是为了让 Spring 把这个环境变量纳入属性源，JSON 里的占位符才能解析成功。如果你发现 JSON 里的 Key 没注入进去，先检查这一行。

另外，@amap/amap-maps-mcp-server是通过npx拉起的，所以本机需要装 Node.js，并且npx在 PATH 里可用。第一次运行会下载包，网络慢的话启动会卡几秒，属于正常现象。如果你所在的环境不方便用npx，也可以改成全局安装后直接用命令启动，但args的写法要相应调整。

4. 验证请求：从 ToolCallback 列表到高德天气查询

配置写完之后，先别急着写复杂 Agent，第一步是确认 MCP 工具真的被加载进来了。写一个最简单的测试接口：

@RestController public class McpTestController { private final ToolCallbackProvider toolCallbackProvider; public McpTestController(ToolCallbackProvider toolCallbackProvider) { this.toolCallbackProvider = toolCallbackProvider; } @GetMapping("/mcp/tools") public String listTools() { ToolCallback[] callbacks = toolCallbackProvider.getToolCallbacks(); return JSON.toJSONString(callbacks); } }

启动项目，访问http://localhost:8080/mcp/tools。如果配置正确，返回的 JSON 里应该能看到高德 MCP 暴露的工具列表，比如maps_weather、maps_geo、maps_regeocode之类。这一步的意义在于把「MCP Server 是否拉起成功」和「模型是否能调用」分开验证。如果这里返回空数组，说明 MCP 客户端没读到配置，问题在application.yml或 JSON 文件路径；如果这里报错说npx找不到，问题在 Node 环境。

工具列表确认之后，再写 Agent 调用。下面这段代码和常见的 ReactAgent 写法一致，重点是绑定toolCallbackProvider：

@GetMapping("/mcp/weather") public String weather(@RequestParam String question) { ChatModel chatModel = ...; // 由 TaoToken 配置驱动的 ChatModel ReactAgent agent = ReactAgent.builder() .name("amap_agent") .model(chatModel) .description("你是一个基于高德地图服务的地理与天气助手") .saver(new MemorySaver()) .toolCallbackProviders(toolCallbackProvider) .build(); RunnableConfig config = RunnableConfig.builder() .threadId("session-" + System.currentTimeMillis()) .build(); Flux<NodeOutput> stream = agent.stream(question, config); StringBuilder answer = new StringBuilder(); stream.doOnNext(output -> { if ("_AGENT_MODEL_".equals(output.node())) { answer.append(((StreamingOutput<?>) output).message().getText()); } else if ("_AGENT_TOOL_".equals(output.node())) { answer.append("\n[Tool Call] ") .append(((ToolResponseMessage) ((StreamingOutput<?>) output).message()) .getResponses().get(0)) .append("\n"); } }).doOnError(e -> System.err.println("Stream Error: " + e.getMessage())) .blockLast(); return answer.toString(); }

访问http://localhost:8080/mcp/weather?question=上海未来三天天气怎么样，预期能看到两段输出：一段是[Tool Call]标记的工具调用结果，另一段是模型基于工具结果生成的自然语言回答。如果只看到模型回答但没有工具调用，说明模型没有选择调用工具，可以检查description是否足够明确，或者换一个更依赖实时数据的问题，比如「北京朝阳区现在天气如何」。

这里有个细节值得注意：threadId每次请求都换一个新的，是为了避免多轮对话状态串扰。如果你要做连续对话，可以把它换成固定的 session id，配合MemorySaver使用。另外，_AGENT_MODEL_和_AGENT_TOOL_这两个节点名是 Spring AI Alibaba 的约定，不同版本可能有细微差异，如果发现输出为空，可以先打印所有output.node()看看实际节点名。

5. 本篇常见错排查

配置和代码都给了，但实际跑起来大概率会遇到几个典型问题。这一节按「现象 → 原因 → 处理」的方式列出来，方便对照。

现象一：启动时报Cannot resolve placeholder 'AMAP_MAPS_API_KEY'。原因是mcp-servers-config.json里的占位符没有被解析。前面提过，Spring 解析占位符依赖属性源，如果application.yml里没有amap.maps.api-key: ${AMAP_MAPS_API_KEY}这一行，或者环境变量没设置，就会报这个错。处理方式是确认环境变量已导出，并且在application.yml里显式声明该属性。如果你不想用占位符，也可以直接把 Key 写进 JSON，但要注意仓库安全。

现象二：/mcp/tools返回空数组。优先检查spring.ai.mcp.client.stdio.servers-configuration的路径是否正确。classpath:/mcp-servers-config.json对应的是src/main/resources/mcp-servers-config.json，如果文件放在子目录里，路径要相应调整。其次检查toolcallback.enabled是否为true，这个开关关掉的话工具不会注册。最后确认spring.ai.mcp.client.type是async，同步模式下部分版本的行为不一致。

现象三：工具列表有，但调用时报npx: command not found。这是运行环境的问题，不是配置问题。MCP Server 是通过npx拉起的子进程，如果部署环境里没有 Node.js，就会失败。处理方式是在运行环境安装 Node.js，或者把@amap/amap-maps-mcp-server全局安装后改用绝对路径启动。容器化部署时尤其要注意基础镜像里是否包含 Node。

现象四：高德接口返回INVALID_USER_KEY或类似鉴权错误。这说明AMAP_MAPS_API_KEY注入成功，但 Key 本身无效。常见原因有三个：一是申请时服务平台选错了，高德 MCP 需要的是「Web 服务」类型的 Key，不是「Web 端」或「iOS/Android」；二是 Key 有 IP 或域名白名单限制，本地调试时没把当前出口 IP 加进去；三是 Key 还没生效，刚创建的高德 Key 有时需要等几分钟。处理方式是回高德开放平台核对 Key 类型和白名单设置。

现象五：模型不调用工具，直接编造答案。这种情况通常是模型侧的问题，不是 MCP 侧。可以先把description写得更具体，明确告诉模型「涉及地理位置、天气、路线时必须调用工具」。如果还是不调用，检查 TaoToken 配置的模型是否支持 function calling，部分轻量模型对工具调用的支持不完整。可以在模型对话页面先手动测试一下该模型的工具调用能力，入口是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

现象六：请求超时。高德 MCP Server 首次启动需要下载 npm 包，如果request-timeout设得太短，第一次请求容易超时。建议首次运行时把超时调到 30s，等包缓存后再调回 10s。另外，如果同时注册了多个 MCP Server，启动时间会叠加，超时值要留足余量。

排查完这些，基本能覆盖从配置到调用的主要故障点。如果问题出在模型侧，比如 Key 无效、额度不足、模型名写错，可以到控制台核对 Key 状态，入口是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，或者查阅接入文档，入口是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

6. 多服务扩展时的 Key 管理建议

跑通高德这一个服务之后，下一步大概率是接第二个、第三个 MCP 服务。这时候配置骨架的价值就体现出来了：模型侧的 Key 始终是 TaoToken 那一个，新增服务只需要在mcp-servers-config.json里加一个条目，并在application.yml里补一行对应的属性声明。

比如再接一个天气服务，JSON 变成：

{ "mcpServers": { "amap-maps": { "command": "npx", "args": ["-y", "@amap/amap-maps-mcp-server"], "env": { "AMAP_MAPS_API_KEY": "${AMAP_MAPS_API_KEY}" } }, "another-service": { "command": "npx", "args": ["-y", "some-mcp-server"], "env": { "SOME_SERVICE_KEY": "${SOME_SERVICE_KEY}" } } } }

application.yml里对应加：

some: service: key: ${SOME_SERVICE_KEY}

这样每个服务的 Key 仍然独立，但注入方式统一，仓库里不出现明文。如果你团队里多人协作，可以把环境变量写进.env文件并加入.gitignore，或者用 CI 的 secrets 管理。TaoToken 的 Key 因为只有一个，管理成本最低，换环境时只改一处。

对于长期做编码类 Agent 的场景，如果调用频率高，可以关注 Coding Plan，入口是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它在高频工具调用下的成本结构更友好。如果你用的是 Claude Code 这类工具，也可以参考对应的接入方式，入口是 https://taotoken.net/claude-code?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后留一个实操建议：每次新增 MCP 服务后，先访问/mcp/tools确认工具列表，再写 Agent 调用。这个习惯能帮你把「服务注册」和「模型调用」两类问题分开，排查效率会高很多。配置骨架本身不复杂，难的是 Key 的边界清晰——模型侧的归 TaoToken，服务侧的归各平台，两者在application.yml里汇合，但职责不混。