1. 为什么单机 MCP Server 在企业里跑不起来很多同学第一次接触 MCPModel Context Protocol都是在本地跑一个 stdio 的 ServerClaude Desktop 或者 Cline 里配一行命令就能用感觉挺爽。但一旦把这个东西搬到公司内网、要对接 ERP、要查财务库、要给几十个业务方共用单机模式立刻就崩了。我踩过的坑是本地调试一切正常上线第二天运维找过来说那台跑 MCP Server 的机器 CPU 打满因为三个部门同时在用同一个库存查询工具。问题的本质在于MCP 在企业场景下已经不是一个给 AI 用的插件而是一个标准的后端服务。它需要注册、发现、健康检查、负载均衡、配置热更新、限流降级——这些恰好就是微服务那一套。所以正确的思路不是给 MCP 加个反向代理而是把 MCP Server 当成微服务来治理用 Nacos 做注册中心用 Spring AI Alibaba 做客户端侧的自动发现与工具注入。这一篇要解决的就是这条链路MCP Server 启动时怎么注册到 Nacos、Spring AI Alibaba 的 Client 怎么从 Nacos 拉到实例列表、怎么把远程工具注入给大模型、多节点部署时怎么验证连通性、以及 401、local proxy failed、OAuth 这些真实报错怎么排。适合有 Spring Boot 基础、正在做企业级 AI Agent 落地的后端同学也适合想把现有微服务能力复用到 AI 场景的架构同学。先说清楚三个核心组件各自扮演什么角色。Spring AI Alibaba 是 Spring AI 的阿里云原生实现深度集成了通义千问系列模型提供了 ChatClient、ToolCallback 这些高阶抽象让你不用手写 HTTP 就能调模型。MCP 是 Anthropic 提出的开放协议让模型以标准化方式连接外部工具和数据源工具描述、参数 schema、调用结果都有统一格式。Nacos 是服务发现与配置管理平台负责维护 MCP Server 的实例列表、健康状态和动态配置。三者组合起来MCP Server 就是ProviderNacos 是注册中心Spring AI Alibaba Client 是Consumer整条链路和普通微服务调用没有本质区别只是传输的内容从业务 JSON 变成了工具调用。理解了这层映射后面所有配置你都会觉得眼熟。下面从环境准备开始一步步把这条链路搭起来。2. TaoToken 前置准备模型接入与 Key 获取在动手写 Nacos 配置之前得先把模型这一侧打通。Spring AI Alibaba 默认走的是 DashScope但企业里经常需要统一网关、统一计费、统一 Key 管理这时候用 TaoToken 这类兼容 OpenAI 协议的接入点会更省事——它同时支持模型对话、Coding Plan、API Key 管理Claude Code、Cline 这类工具也能直接对接。第一步是拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key注意创建时选择对应的权限范围生产环境建议单独建一个 Key不要和测试混用。创建完复制出来这个 Key 只会显示一次丢了只能重建。第二步是确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数直接作为 OpenAI 兼容的 base_url 使用。如果你用的是 Spring AI Alibaba 的 OpenAI 兼容模式配置里就填这个如果走 DashScope 原生协议则需要另外的 endpoint这里我们统一用 OpenAI 兼容模式方便和 Nacos 配置中心配合。第三步是选模型。企业场景下建议先用 qwen-max 或者 qwen-plus 做验证前者能力强适合复杂工具调用后者性价比高适合高并发。模型 ID 要写全比如qwen-max不要写别名。如果你不确定当前账号能用哪些模型可以直接在 https://taotoken.net/api 的模型对话页面里试一下输入一句话看返回确认 Key 和模型都正常。第四步是把这些信息写进 Nacos 配置中心而不是硬编码在代码里。这是分布式架构的关键——模型参数、Prompt 模板、工具白名单都应该能热更新。下面这段就是 Nacos 里的配置片段Data ID 建议用ai-service-config.yamlGroup 用DEFAULT_GROUP命名空间按环境隔离生产用 prod测试用 testspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: qwen-max temperature: 0.7 max-tokens: 2048 alibaba: mcp: enabled: true client: discovery-enabled: true service-name: mcp-server-provider注意api-key这里用了占位符${TAOTOKEN_API_KEY}实际值通过环境变量或者 Nacos 的加密配置注入不要明文写在配置文件里。这一步做完模型侧就准备好了接下来搭 MCP Server 并让它注册到 Nacos。3. 可复制配置MCP Server 注册与 Client 发现这一节是整篇的核心所有配置都可以直接复制。先看 MCP Server 端。3.1 MCP Server 的 pom 与启动类新建一个 Spring Boot 3.x 项目JDK 17 以上。pom 里需要三个关键依赖Nacos 服务发现、Spring AI Alibaba starter、以及 MCP Server 的实现Spring AI 提供了spring-ai-mcp-server-spring-boot-starter但企业里更常用自定义的 HTTP/gRPC 传输这里我们用 Spring AI Alibaba 封装好的方式dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-ai-alibaba-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId /dependency启动类上加EnableDiscoveryClient让服务启动时自动向 Nacos 注册SpringBootApplication EnableDiscoveryClient public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } }application.yml 里配置 Nacos 地址和服务名服务名mcp-server-provider就是后面 Client 要发现的目标server: port: 8081 spring: application: name: mcp-server-provider cloud: nacos: discovery: server-addr: 192.168.1.10:8848 namespace: prod group: DEFAULT_GROUP metadata: mcp-protocol: http mcp-version: 1.0.0metadata 里加上mcp-protocol和mcp-version是个好习惯Client 侧可以根据这些元数据做协议版本路由后面多版本共存时很有用。3.2 工具实现与暴露工具类用Tool注解Spring AI Alibaba 会自动扫描并注册到 MCP Server 的工具列表里Component public class StockTools { Tool(description 根据商品ID查询企业实时库存返回剩余件数) public String getStockLevel(String productId) { // 实际业务里这里查数据库或调用 ERP return ID: productId 剩余库存: 1500 件; } Tool(description 查询指定仓库的库存周转率) public String getTurnoverRate(String warehouseId, String month) { return 仓库 warehouseId 在 month 的周转率为 3.2; } }工具描述一定要写清楚这是大模型决定要不要调用、怎么填参数的唯一依据。描述含糊会导致模型乱调或者不调这是最常见的工具不生效原因。3.3 Client 侧的发现与注入Client 端同样加 Nacos discovery 依赖然后通过DiscoveryClient拿到实例列表构建 McpClientService public class EnterpriseAiAgent { Autowired private DiscoveryClient discoveryClient; Autowired private ChatModel chatModel; public String askAi(String question) { ListServiceInstance instances discoveryClient.getInstances(mcp-server-provider); if (instances.isEmpty()) { throw new IllegalStateException(没有可用的 MCP Server 实例); } McpClient mcpClient McpClient.builder() .instances(instances) .loadBalancer(roundRobin) .build(); return ChatClient.create(chatModel) .withMcp(mcpClient) .prompt(question) .call() .content(); } }如果你用的是 Claude Code 或者 Cline 这类外部工具对接 MCP配置格式不一样需要写全三件套。以 Cline 的 MCP 配置为例在cline_mcp_settings.json里{ mcpServers: { enterprise-stock: { url: http://192.168.1.10:8081/mcp, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} }, model: qwen-max } } }Base URL、Key、Model ID 三件套缺一不可少任何一个都会在调用时报 401 或者模型找不到。Codex 用户则在~/.codex/auth.json里配置对应的 base_url 和 api_key格式类似这里不展开。3.4 Nacos 配置中心的热更新把模型参数和 Prompt 模板放到 Nacos 配置中心Client 侧加RefreshScope就能热更新RestController RefreshScope public class ConfigController { Value(${spring.ai.openai.chat.options.model:qwen-max}) private String model; GetMapping(/current-model) public String currentModel() { return model; } }改完 Nacos 里的配置点发布Client 侧不用重启就能生效。这在多节点部署时特别有用——你不需要逐台机器改配置。4. 验证请求分布式调用连通性检查配置写完不代表链路通了必须一步步验证。我一般按这个顺序查。第一步确认 MCP Server 已经注册到 Nacos。打开 Nacos 控制台进入服务管理 - 服务列表命名空间选 prod看mcp-server-provider是否在列表里实例数是不是你启动的节点数。如果不在检查server-addr是否可达、namespace 是否写对、防火墙是否放行 8848 端口。第二步直接 curl MCP Server 的健康端点确认服务本身活着curl -i http://192.168.1.10:8081/actuator/health返回{status:UP}说明服务正常。如果 404检查是否引入了 actuator 依赖。第三步验证 Client 能拉到实例。写一个测试接口GetMapping(/instances) public ListString instances() { return discoveryClient.getInstances(mcp-server-provider) .stream() .map(i - i.getHost() : i.getPort()) .collect(Collectors.toList()); }访问这个接口应该返回所有在线节点的地址列表。如果返回空说明 Client 的 Nacos 配置和服务端不一致重点查 namespace 和 group。第四步发起一次真实的工具调用。用模型对话页面或者直接调 Client 的 askAi 接口问帮我查一下商品 P12345 的库存。正常返回应该是模型先决定调用getStockLevel然后返回ID: P12345 剩余库存: 1500 件。如果模型没调工具而是自己编了一个答案说明工具没注入成功检查withMcp是否生效、工具描述是否被正确扫描。第五步多节点验证。启动第二个 MCP Server 实例端口改成 8082服务名不变。再访问/instances应该看到两个地址。然后连续调几次 askAi观察日志里实际命中的是哪个节点确认轮询生效。把其中一个节点 kill 掉等 Nacos 健康检查剔除默认 15 秒左右再调应该只走剩下的节点。这一步验证通过分布式链路就算通了。5. 本篇常见错误排查这一节列的都是真实遇到过的报错对照着查能省很多时间。401 Unauthorized。最常见的原因是 Key 没传对或者传了但格式不对。检查三处Nacos 配置里的api-key是否被正确解析占位符有没有被环境变量替换、请求头里是不是Authorization: Bearer xxx格式、Key 是否过期。如果是 Cline 或 Claude Code 报 401检查cline_mcp_settings.json里的 headers 有没有写对很多人漏了Bearer前缀。local proxy failed。这个报错通常出现在 Client 侧连不上 MCP Server 的时候。先确认 Server 的端口是否监听、防火墙是否放行、Nacos 里注册的 IP 是不是内网可达的地址。有个坑是 Nacos 默认注册的是容器内网 IP如果 Client 在宿主机上跑就连不上需要在配置里指定spring.cloud.nacos.discovery.ip为宿主机 IP。reading choices 报错。这是 OpenAI 兼容协议返回体解析失败一般是 base_url 写错或者模型返回了非标准格式。检查base-url是不是https://taotoken.net/api注意结尾不要多加/v1或者斜杠。如果用的是自建网关确认它返回的 JSON 里有choices字段。OAuth 相关报错。如果 MCP Server 开了 Spring Security 的 OAuth2 保护Client 侧需要带上 access token。检查 token 是否过期、scope 是否包含工具调用权限。企业里建议用 Nacos 的命名空间隔离 网关统一鉴权不要在 MCP Server 上单独做一套 OAuth维护成本太高。工具不生效模型不调用。九成是工具描述写得太模糊或者参数类型不匹配。把Tool的 description 写具体参数用 String、int 这类基础类型复杂对象先转成 JSON 字符串传。另外确认 Client 侧的withMcp真的把工具注入了可以在日志里打印工具列表确认。Nacos 实例列表为空。检查 namespace、group、服务名三处是否完全一致大小写敏感。还要确认 Client 和服务端用的是同一个 Nacos 集群跨集群是发现不了的。6. 从单机到集群的落地建议链路跑通之后还有几件事值得做。负载均衡建议直接用 Spring Cloud LoadBalancer配置roundRobin或者random不要自己写轮询逻辑。限流降级可以接 Sentinel给高耗能的工具比如大数据查询单独设 QPS 阈值防止模型疯狂调用打垮底层库。监控方面把 MCP 调用的耗时、成功率、工具命中分布打到 Prometheus配合 Grafana 看板能快速定位是模型侧慢还是工具侧慢。配置管理上生产环境的 Key 一定要走加密配置或者环境变量不要明文进 Git。命名空间按环境隔离prod 和 test 的 Nacos 配置不要共用。多版本共存时用 metadata 里的mcp-version做路由Client 侧根据版本选择对应的实例组。如果你还在选模型接入方案可以先用模型对话页面验证 Key 和模型是否正常再决定是走 Coding Plan 还是按量计费。长期做 Agent 开发的团队Coding Plan 在成本上通常更划算。接入文档里有完整的参数说明和示例遇到协议细节问题可以直接查。最后提醒一句MCP 分布式化的核心不是技术多复杂而是把服务治理这套成熟经验复用到 AI 工具链上。Nacos 负责发现Spring AI Alibaba 负责注入你负责把工具描述写清楚。这三件事做好企业级 MCP 就稳了。 
长河君 · 2026/10/4 16:07:26 · 阅读 1.2k Spring AI Alibaba + Nacos 分布式架构实战教程（非常详细）：企业级 MCP 从入门到精通，收藏这一篇就够了！
1. 为什么单机 MCP Server 在企业里跑不起来很多同学第一次接触 MCPModel Context Protocol都是在本地跑一个 stdio 的 ServerClaude Desktop 或者 Cline 里配一行命令就能用感觉挺爽。但一旦把这个东西搬到公司内网、要对接 ERP、要查财务库、要给几十个业务方共用单机模式立刻就崩了。我踩过的坑是本地调试一切正常上线第二天运维找过来说那台跑 MCP Server 的机器 CPU 打满因为三个部门同时在用同一个库存查询工具。问题的本质在于MCP 在企业场景下已经不是一个给 AI 用的插件而是一个标准的后端服务。它需要注册、发现、健康检查、负载均衡、配置热更新、限流降级——这些恰好就是微服务那一套。所以正确的思路不是给 MCP 加个反向代理而是把 MCP Server 当成微服务来治理用 Nacos 做注册中心用 Spring AI Alibaba 做客户端侧的自动发现与工具注入。这一篇要解决的就是这条链路MCP Server 启动时怎么注册到 Nacos、Spring AI Alibaba 的 Client 怎么从 Nacos 拉到实例列表、怎么把远程工具注入给大模型、多节点部署时怎么验证连通性、以及 401、local proxy failed、OAuth 这些真实报错怎么排。适合有 Spring Boot 基础、正在做企业级 AI Agent 落地的后端同学也适合想把现有微服务能力复用到 AI 场景的架构同学。先说清楚三个核心组件各自扮演什么角色。Spring AI Alibaba 是 Spring AI 的阿里云原生实现深度集成了通义千问系列模型提供了 ChatClient、ToolCallback 这些高阶抽象让你不用手写 HTTP 就能调模型。MCP 是 Anthropic 提出的开放协议让模型以标准化方式连接外部工具和数据源工具描述、参数 schema、调用结果都有统一格式。Nacos 是服务发现与配置管理平台负责维护 MCP Server 的实例列表、健康状态和动态配置。三者组合起来MCP Server 就是ProviderNacos 是注册中心Spring AI Alibaba Client 是Consumer整条链路和普通微服务调用没有本质区别只是传输的内容从业务 JSON 变成了工具调用。理解了这层映射后面所有配置你都会觉得眼熟。下面从环境准备开始一步步把这条链路搭起来。2. TaoToken 前置准备模型接入与 Key 获取在动手写 Nacos 配置之前得先把模型这一侧打通。Spring AI Alibaba 默认走的是 DashScope但企业里经常需要统一网关、统一计费、统一 Key 管理这时候用 TaoToken 这类兼容 OpenAI 协议的接入点会更省事——它同时支持模型对话、Coding Plan、API Key 管理Claude Code、Cline 这类工具也能直接对接。第一步是拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key注意创建时选择对应的权限范围生产环境建议单独建一个 Key不要和测试混用。创建完复制出来这个 Key 只会显示一次丢了只能重建。第二步是确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数直接作为 OpenAI 兼容的 base_url 使用。如果你用的是 Spring AI Alibaba 的 OpenAI 兼容模式配置里就填这个如果走 DashScope 原生协议则需要另外的 endpoint这里我们统一用 OpenAI 兼容模式方便和 Nacos 配置中心配合。第三步是选模型。企业场景下建议先用 qwen-max 或者 qwen-plus 做验证前者能力强适合复杂工具调用后者性价比高适合高并发。模型 ID 要写全比如qwen-max不要写别名。如果你不确定当前账号能用哪些模型可以直接在 https://taotoken.net/api 的模型对话页面里试一下输入一句话看返回确认 Key 和模型都正常。第四步是把这些信息写进 Nacos 配置中心而不是硬编码在代码里。这是分布式架构的关键——模型参数、Prompt 模板、工具白名单都应该能热更新。下面这段就是 Nacos 里的配置片段Data ID 建议用ai-service-config.yamlGroup 用DEFAULT_GROUP命名空间按环境隔离生产用 prod测试用 testspring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: qwen-max temperature: 0.7 max-tokens: 2048 alibaba: mcp: enabled: true client: discovery-enabled: true service-name: mcp-server-provider注意api-key这里用了占位符${TAOTOKEN_API_KEY}实际值通过环境变量或者 Nacos 的加密配置注入不要明文写在配置文件里。这一步做完模型侧就准备好了接下来搭 MCP Server 并让它注册到 Nacos。3. 可复制配置MCP Server 注册与 Client 发现这一节是整篇的核心所有配置都可以直接复制。先看 MCP Server 端。3.1 MCP Server 的 pom 与启动类新建一个 Spring Boot 3.x 项目JDK 17 以上。pom 里需要三个关键依赖Nacos 服务发现、Spring AI Alibaba starter、以及 MCP Server 的实现Spring AI 提供了spring-ai-mcp-server-spring-boot-starter但企业里更常用自定义的 HTTP/gRPC 传输这里我们用 Spring AI Alibaba 封装好的方式dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId /dependency dependency groupIdcom.alibaba.cloud/groupId artifactIdspring-ai-alibaba-starter/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-mcp-server-spring-boot-starter/artifactId /dependency启动类上加EnableDiscoveryClient让服务启动时自动向 Nacos 注册SpringBootApplication EnableDiscoveryClient public class McpServerApplication { public static void main(String[] args) { SpringApplication.run(McpServerApplication.class, args); } }application.yml 里配置 Nacos 地址和服务名服务名mcp-server-provider就是后面 Client 要发现的目标server: port: 8081 spring: application: name: mcp-server-provider cloud: nacos: discovery: server-addr: 192.168.1.10:8848 namespace: prod group: DEFAULT_GROUP metadata: mcp-protocol: http mcp-version: 1.0.0metadata 里加上mcp-protocol和mcp-version是个好习惯Client 侧可以根据这些元数据做协议版本路由后面多版本共存时很有用。3.2 工具实现与暴露工具类用Tool注解Spring AI Alibaba 会自动扫描并注册到 MCP Server 的工具列表里Component public class StockTools { Tool(description 根据商品ID查询企业实时库存返回剩余件数) public String getStockLevel(String productId) { // 实际业务里这里查数据库或调用 ERP return ID: productId 剩余库存: 1500 件; } Tool(description 查询指定仓库的库存周转率) public String getTurnoverRate(String warehouseId, String month) { return 仓库 warehouseId 在 month 的周转率为 3.2; } }工具描述一定要写清楚这是大模型决定要不要调用、怎么填参数的唯一依据。描述含糊会导致模型乱调或者不调这是最常见的工具不生效原因。3.3 Client 侧的发现与注入Client 端同样加 Nacos discovery 依赖然后通过DiscoveryClient拿到实例列表构建 McpClientService public class EnterpriseAiAgent { Autowired private DiscoveryClient discoveryClient; Autowired private ChatModel chatModel; public String askAi(String question) { ListServiceInstance instances discoveryClient.getInstances(mcp-server-provider); if (instances.isEmpty()) { throw new IllegalStateException(没有可用的 MCP Server 实例); } McpClient mcpClient McpClient.builder() .instances(instances) .loadBalancer(roundRobin) .build(); return ChatClient.create(chatModel) .withMcp(mcpClient) .prompt(question) .call() .content(); } }如果你用的是 Claude Code 或者 Cline 这类外部工具对接 MCP配置格式不一样需要写全三件套。以 Cline 的 MCP 配置为例在cline_mcp_settings.json里{ mcpServers: { enterprise-stock: { url: http://192.168.1.10:8081/mcp, headers: { Authorization: Bearer ${TAOTOKEN_API_KEY} }, model: qwen-max } } }Base URL、Key、Model ID 三件套缺一不可少任何一个都会在调用时报 401 或者模型找不到。Codex 用户则在~/.codex/auth.json里配置对应的 base_url 和 api_key格式类似这里不展开。3.4 Nacos 配置中心的热更新把模型参数和 Prompt 模板放到 Nacos 配置中心Client 侧加RefreshScope就能热更新RestController RefreshScope public class ConfigController { Value(${spring.ai.openai.chat.options.model:qwen-max}) private String model; GetMapping(/current-model) public String currentModel() { return model; } }改完 Nacos 里的配置点发布Client 侧不用重启就能生效。这在多节点部署时特别有用——你不需要逐台机器改配置。4. 验证请求分布式调用连通性检查配置写完不代表链路通了必须一步步验证。我一般按这个顺序查。第一步确认 MCP Server 已经注册到 Nacos。打开 Nacos 控制台进入服务管理 - 服务列表命名空间选 prod看mcp-server-provider是否在列表里实例数是不是你启动的节点数。如果不在检查server-addr是否可达、namespace 是否写对、防火墙是否放行 8848 端口。第二步直接 curl MCP Server 的健康端点确认服务本身活着curl -i http://192.168.1.10:8081/actuator/health返回{status:UP}说明服务正常。如果 404检查是否引入了 actuator 依赖。第三步验证 Client 能拉到实例。写一个测试接口GetMapping(/instances) public ListString instances() { return discoveryClient.getInstances(mcp-server-provider) .stream() .map(i - i.getHost() : i.getPort()) .collect(Collectors.toList()); }访问这个接口应该返回所有在线节点的地址列表。如果返回空说明 Client 的 Nacos 配置和服务端不一致重点查 namespace 和 group。第四步发起一次真实的工具调用。用模型对话页面或者直接调 Client 的 askAi 接口问帮我查一下商品 P12345 的库存。正常返回应该是模型先决定调用getStockLevel然后返回ID: P12345 剩余库存: 1500 件。如果模型没调工具而是自己编了一个答案说明工具没注入成功检查withMcp是否生效、工具描述是否被正确扫描。第五步多节点验证。启动第二个 MCP Server 实例端口改成 8082服务名不变。再访问/instances应该看到两个地址。然后连续调几次 askAi观察日志里实际命中的是哪个节点确认轮询生效。把其中一个节点 kill 掉等 Nacos 健康检查剔除默认 15 秒左右再调应该只走剩下的节点。这一步验证通过分布式链路就算通了。5. 本篇常见错误排查这一节列的都是真实遇到过的报错对照着查能省很多时间。401 Unauthorized。最常见的原因是 Key 没传对或者传了但格式不对。检查三处Nacos 配置里的api-key是否被正确解析占位符有没有被环境变量替换、请求头里是不是Authorization: Bearer xxx格式、Key 是否过期。如果是 Cline 或 Claude Code 报 401检查cline_mcp_settings.json里的 headers 有没有写对很多人漏了Bearer前缀。local proxy failed。这个报错通常出现在 Client 侧连不上 MCP Server 的时候。先确认 Server 的端口是否监听、防火墙是否放行、Nacos 里注册的 IP 是不是内网可达的地址。有个坑是 Nacos 默认注册的是容器内网 IP如果 Client 在宿主机上跑就连不上需要在配置里指定spring.cloud.nacos.discovery.ip为宿主机 IP。reading choices 报错。这是 OpenAI 兼容协议返回体解析失败一般是 base_url 写错或者模型返回了非标准格式。检查base-url是不是https://taotoken.net/api注意结尾不要多加/v1或者斜杠。如果用的是自建网关确认它返回的 JSON 里有choices字段。OAuth 相关报错。如果 MCP Server 开了 Spring Security 的 OAuth2 保护Client 侧需要带上 access token。检查 token 是否过期、scope 是否包含工具调用权限。企业里建议用 Nacos 的命名空间隔离 网关统一鉴权不要在 MCP Server 上单独做一套 OAuth维护成本太高。工具不生效模型不调用。九成是工具描述写得太模糊或者参数类型不匹配。把Tool的 description 写具体参数用 String、int 这类基础类型复杂对象先转成 JSON 字符串传。另外确认 Client 侧的withMcp真的把工具注入了可以在日志里打印工具列表确认。Nacos 实例列表为空。检查 namespace、group、服务名三处是否完全一致大小写敏感。还要确认 Client 和服务端用的是同一个 Nacos 集群跨集群是发现不了的。6. 从单机到集群的落地建议链路跑通之后还有几件事值得做。负载均衡建议直接用 Spring Cloud LoadBalancer配置roundRobin或者random不要自己写轮询逻辑。限流降级可以接 Sentinel给高耗能的工具比如大数据查询单独设 QPS 阈值防止模型疯狂调用打垮底层库。监控方面把 MCP 调用的耗时、成功率、工具命中分布打到 Prometheus配合 Grafana 看板能快速定位是模型侧慢还是工具侧慢。配置管理上生产环境的 Key 一定要走加密配置或者环境变量不要明文进 Git。命名空间按环境隔离prod 和 test 的 Nacos 配置不要共用。多版本共存时用 metadata 里的mcp-version做路由Client 侧根据版本选择对应的实例组。如果你还在选模型接入方案可以先用模型对话页面验证 Key 和模型是否正常再决定是走 Coding Plan 还是按量计费。长期做 Agent 开发的团队Coding Plan 在成本上通常更划算。接入文档里有完整的参数说明和示例遇到协议细节问题可以直接查。最后提醒一句MCP 分布式化的核心不是技术多复杂而是把服务治理这套成熟经验复用到 AI 工具链上。Nacos 负责发现Spring AI Alibaba 负责注入你负责把工具描述写清楚。这三件事做好企业级 MCP 就稳了。