ai-agent框架spring ai alibaba (三)外部调用II-2 分布式MCP

简介

spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一) 架构 完成

系列(三) 调用

I 工具 完成

II MCP

1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置 完成

2 分布式 MCP 注册和发现@nacos，gateway

3 MCP security, oauth2

III skills 完成

系列(四) RAG 完成

I 知识库，文档读取，分块；嵌入，向量store

II 检索，增强生成，模块化；混合检索，融合重排

系列(二) I 模型 model模型 完成

chat模型，消息，提示词，结构化输出，记忆

chat client，advisor组件

II 提示词工程@nacos

系列(五) graph 完成

I 图结构，节点和边；StateGraph；外部介入 完成

推理框架 graph映射: ReAct，relection，CoT，Plan-And-Execute

II 图编译 CompiledGraph，扁平化图结构，邻接表结构 完成

III 图执行，响应式流执行，检查点，回溯/回放，中断和恢复，容错

系列(六) agent及组件 ReactAgent，AgentLlmNode，AgentToolNode，钩子和拦截器，记忆，结构化输出

系列(七) MAS

I MAS模式 flow模式 编排器-子智能体，智能体团队；数据交接

II 分布式MAS，远程通讯，负载均衡，注册发现，容错

系列(八) 观测

I 观测组件(micrometer-observation), langfuse

II spring ai观测，观测组件，ChatClient，ChatModel

III spring ai alibaba观测 图观测

系列(九) 评估 I spring ai 评估组件 本地开发测试

II spring ai alibaba admin，数据集构建、线上链路数据复用，试验，评估器

III langfuse评估

系列(十) 沙箱

本文分析外部调用II-2 分布式MCP

based spring ai aliba ba v1.1.2.2，spring ai v1.1.2，MCP sdk 0.17.0

外部调用

如果说agent是一个人，大模型是大脑，调用是手脚，执行动作干实事。调用在不断发展演变中，目前已有工具，MCP，skills，CLI等多种方式

MCP-sdk MCP的实现，包括连接管理，会话和传输协议，能力(资源，工具等)，本文不分析MCP原理源码，重点放在sa/saa集成MCP，saa分布式MCP

分布式MCP

MCP没有分布式相关的规范，得益于java成熟的微服务体系，saa实现分布式MCP是水到渠成的事，nacos v3原生支持MCP服务注册和发现，分布式MCP client 依赖 nacos 的发现能力和变更通知能力，实现MCP调用的负载均衡和容错，实现动态更新MCP server instances

分布式client

本节分析分布式MCP client，MCP Client 集群化、分布式改造，解决单点故障、流量洪峰和配置中心动态感知的问题。

上图 分布式mcp client和工具类图，整体架构可分为"接口定义 - 多协议实现 - 服务治理"3部分

核心接口定义

1. DistributedSyncMcpClient：分布式客户端接口

getServerName 获取服务名，一般是工具MCP工具名称

callTool（调用工具）、listTools（列出工具） 工具调用方法

getMcpSyncClient 获取底层同步客户端，分布式核心方法，Mcp client列表依据负责算法选择 一实例，名称改为selectMcpClient更好

init /subscribe init 从nacos获取服务实例，subscribe订阅服务的变更，包括服务的上线和下线

2. ToolCallback：Spring AI agent工具接口

3. NacosMcpSubscriber： Nacos 服务订阅接口，感知分布式mcp client动态变化

实现类

1. SseWebFluxDistributedSyncMcpClient：DistributedSyncMcpClient see同步实现，处理SSE 协议的通信。它内部维护了一个 McpSyncClient 的列表，并依赖 NacosMcpOperationService 进行服务发现和变更更新。
2. StreamWebFluxDistributedSyncMcpClient： DistributedSyncMcpClient Streamable同步实现，处理Streamable协议的通信。它内部维护了一个 McpSyncClient 的列表，并依赖 NacosMcpOperationService 进行服务发现和变更更新。
3. DistributedSyncMcpToolCallback：实现了 ToolCallback，作为上层Agent应用调用的入口，内部持有 DistributedSyncMcpClient，将具体的工具调用请求委托给分布式客户端处理
4. NacosMcpOperationService：封装了对 Nacos 的读写操作，负责具体的服务注册、发现逻辑，并实现了 NacosMcpSubscriber 接口来监听变化，此类属于common包，后面服务注册，网关用到。

协作流程

1. 初始化与订阅： DistributedSyncMcpClient 启动时，通过 NacosMcpOperationService 获取Nacos 上的 MCP 服务实例，订阅变更。
2. 动态路由：工具调用请求时，DistributedSyncMcpToolCallback 调用 callTool。此时，分布式客户端根据某种负载算法从维护的 McpSyncClient 列表中选择一个可用的客户端。
3. 负载均衡：目前负载均衡算法：int currentIndex = index.getAndUpdate(index -> (index + 1) % syncClients.size())。这是一种典型的轮询策略，用于在多个同步客户端实例间分发请求。
4. 获取McpSyncClient列表下标为currentIndex的实例，完成mcp工具调用

架构抽象层面的不足

当前架构虽然能够正常工作，但从软件工程的设计原则（尤其是开闭原则和单一职责原则）来看，DistributedSyncMcpClient 及其实现类在抽象层次上存在明显不足，主要体现在以下三个方面：

1. 传输协议与分布式逻辑耦合过紧

从类图可以看出，SseWebFluxDistributedSyncMcpClient 同时承担了"分布式管理"（如客户端列表维护、负载均衡）和"SSE 协议通信"的具体实现职责。

• 问题 ：若未来需要支持 gRPC、HTTP/2 等其他传输协议，就必须创建新的实现类（如 GrpcDistributedSyncMcpClient），并重复编写与服务发现、客户端列表维护、负载均衡等与协议无关的分布式逻辑。
• 理想设计 ：应将"分布式代理逻辑"与"传输协议实现"解耦。DistributedSyncMcpClient 应作为纯粹的代理（Proxy），专注于管理 McpSyncClient 实例集合与请求路由，而不关心底层是 SSE 还是 Streamable 协议。底层的 McpSyncClient 应由工厂根据协议类型动态创建并注入。

2. 负载均衡策略硬编码

当前负载均衡采用简单的轮询算法，实现代码为：(index + 1) % syncClients.size()。

• 问题：策略硬编码在实现类中，缺乏灵活性。
• 理想设计 ：应将负载均衡抽象为独立的策略接口（例如 LoadBalanceStrategy）。DistributedSyncMcpClient 持有该接口，具体的算法（如轮询、随机、加权等）可通过构造函数注入或配置文件动态切换。

3. 服务发现机制与具体实现绑定

服务注册与发现目前强依赖 Nacos（通过 NacosMcpOperationService）。这更多是一种产品策略选择（绑定自家生态），而非技术限制，但目前尚无其他注册中心原生支持 MCP 服务。

SseWebFluxDistributedSyncMcpClient 与 StreamWebFluxDistributedSyncMcpClient 的实现代码相似度高达 97%，仅在与传输协议相关的少数几处存在差异。

总结

Spring AI Alibaba 的分布式 MCP Client 已具备核心的路由与通信能力。为了适应未来更复杂的企业级场景，建议在以下三个维度进行更深层次的抽象：实现传输协议无关性、将负载均衡策略化、以及标准化服务发现机制。最终目标是将"做什么"（分布式路由）与"怎么做"（SSE通信、Nacos发现、轮询算法）彻底解耦，提升框架的扩展性与可维护性。

MCP服务注册

上节分析MCP分布式client，依赖nacos的发现功能获得MCP sever的实例。MCP server实例信息是MCP注册器负责注册，MCP server启动后，MCP注册器收集MCP server信息，自动注册到nacos，MCP注册是MCP server的一部分

MCP sever和MCP server实例注册，为了描述方便，前者称为MCP server类型注册

上图 MCP服务和注册类图，本节展示Stateless的类图，非Stateless版本类似，注册包括 3个功能

0 MCP 服务兼容性检查

首先查询是否已有相同的MCP服务注册，查询的key是服务名+版本，若已有，需要检查兼容性

上图是兼容检查的代码，展示检查的项目

1 注册MCP 服务类型

主要从McpStatelessAsyncServer，配置抓取信息，构建：

McpServerBasicInfo MCP服务的信息，包括服务名称，版本，描述，协议(SSE, STREAMABLE)，contextPath

McpToolSpecification MCP工具(集合)的spec，属性包括名称，描述，输入schema

McpEndpointSpec

最后调用NacosMcpOperationService的createMcpServer注册MCP服务类型

**！**有一点需要考虑，注册服务类型在MCP启动时，多个MCP服务同时启动可能出现碰撞，第一个注册后，后面的会失败，NacosStatelessMcpRegister提供容错机制，但比较简单，一，没有采用随机延时防碰撞机制；二，nacos异常是通用的NacosException，实际情况出现注册不上的可能性比较大

2 注册MCP 服务实例

注册实例在onApplicationEvent，ApplicationListener接口的方法，接收参数，目的是过滤掉"management" web server，获取正确的端口，management是spring boot actuator，观测服务，但如果还有其他web server？

MCP服务实例注册信息有3个，与微服务注册一样

服务名称，分组名称

Instance 实例对象

3 订阅变更

MCP服务的订阅与分布式client的订阅一致，关注不同，后者关注实例的上下行，前者关注工具规格的变更

自动配置&示例

本节结合saa的mcp-exampls/mcp-nacos-example实例，分析自动配置，观测运行

自动配置

本节解释示例的自动配置，得益于springboot的自动配置，默认即可用，示例很简单，本节剖开内部，搞清楚示例究竟做了些什么

mcp client

本节解释分布式mcp client应用端，mcp client被agent工具包装，使用与工具是一致

上图 分布式mcp client和工具类图

NacosMcpAutoConfiguration 负责构建NacosMcpOperationService，该服务负责nacos的读写订阅，用于MCP服务类型，MCP服务实例注册，订阅MCP 工具变更

NacosMcpToolCallbackAutoConfiguration 负责构建DistributedSyncMcpToolCallbackProvider，

依赖NacosMcpStreamableClientAutoConfiguration构建的DistributedSyncMcpClient集，

DistributedSyncMcpToolCallbackProvider是ToolCallbackProvider，提供agent工具TooCallback集合

！ 注意，上图只展示 Streamable 协议， sync client ，还有 see 协议， async client

有了上面的自动配置，分布式mcp client应用只需注入ToolCallbackProvider，取出TooCallback，后续调用agent工具般调用mcp工具

mcp服务

分布式mcp服务应用，与mcp client应用相反，读取agent工具信息构建为MCP工具

上图 分布式mcp server构建和注册/订阅，其中右边部分mcp server分析过，mcp server构建，agent工具转换为mcp tool spec，详细可参考mcp server那部分

NacosStatelessMcpRegisterAutoConfiguration 构建注册器，依赖McpServerAutoConfiguration构建的Mcp server

！ 注意，上图展示了 Stateless ， sync server ，还有有状态和异步 server

有了自动配置加持，mcp server示例只需简单声明ToolCallbackProvider即可

运行示例

2.1) 运行mcp服务

上图 mcp server stateless/async的自动配置的断点，收集agent工具，转换为tool spec

上图 服务类型注册，nacos原生支持mcp服务注册，AI注册中心/MCP管理

上图 mcp服务实例，运行两个一样的mcp服务，组成集群

2.2) 运行mcp client

上图 分布式mcp client，获取两个mcp服务实例，DistributedAsyncMcpToolCallbackProvider封装分布式mcp client，提供agent工具

NEXT

mcp gateway