9.1 MCP Client Boot StarterMCP Client Boot Starter Spring AI

MCP Client Boot Starter

Spring AI MCP（模型上下文协议）客户端Boot启动器为Spring Boot应用程序中的MCP客户端功能提供自动配置。它支持同步和异步客户端实现，以及各种传输选项。

MCP客户端Boot启动器提供：

管理多个客户端实例
自动客户端初始化（如果启用）
支持多个命名传输
与Spring AI工具执行框架的集成
当应用程序上下文关闭时，通过自动清理资源进行适当的生命周期管理
通过自定义器进行可定制的客户端创建

Starters

注意： Spring AI自动配置和启动器模块的工件名称发生了重大变更。请参阅升级说明获取更多信息。

标准MCP客户端

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

标准启动器通过STDIO（进程内）和/或SSE（远程）传输同时连接到一个或多个MCP服务器。 SSE连接使用基于HttpClient的传输实现。与MCP服务器的每个连接都会创建一个新的MCP客户端实例。您可以选择SYNC或ASYNC MCP客户端（注意：不能混合同步和异步客户端）。对于生产部署，我们建议使用基于WebFlux的SSE连接与spring-ai-starter-mcp-client-webflux。

WebFlux客户端

WebFlux启动器提供与标准启动器类似的功能，但使用基于WebFlux的SSE传输实现。

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>

配置属性

通用属性

通用属性以spring.ai.mcp.client为前缀：

属性	描述	默认值
`enabled`	启用/禁用MCP客户端	`true`
`name`	MCP客户端实例的名称	`spring-ai-mcp-client`
`version`	MCP客户端实例的版本	`1.0.0`
`initialized`	是否在创建时初始化客户端	`true`
`request-timeout`	MCP客户端请求的超时持续时间	`20s`
`type`	客户端类型（SYNC或ASYNC）。所有客户端必须是同步或异步；不支持混合	`SYNC`
`root-change-notification`	为所有客户端启用/禁用根变更通知	`true`
`toolcallback.enabled`	启用/禁用MCP工具回调与Spring AI工具执行框架的集成	`true`

Stdio传输属性

标准I/O传输的属性以spring.ai.mcp.client.stdio为前缀：

属性	描述	默认值
`servers-configuration`	包含JSON格式MCP服务器配置的资源	-
`connections`	命名的stdio连接配置映射	-
`connections.[name].command`	为MCP服务器执行的命令	-
`connections.[name].args`	命令参数列表	-
`connections.[name].env`	服务器进程的环境变量映射	-

配置示例：

spring:
  ai:
    mcp:
      client:
        stdio:
          root-change-notification: true
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

或者，您可以使用Claude桌面格式通过外部JSON文件配置stdio连接：

spring:
  ai:
    mcp:
      client:
        stdio:
          servers-configuration: classpath:mcp-servers.json

Claude桌面格式如下所示：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

目前，Claude桌面格式仅支持STDIO连接类型。

SSE传输属性

服务器发送事件（SSE）传输的属性以spring.ai.mcp.client.sse为前缀：

属性	描述	默认值
`connections`	命名的SSE连接配置映射	-
`connections.[name].url`	与MCP服务器进行SSE通信的基础URL端点	-
`connections.[name].sse-endpoint`	用于连接的sse端点（作为url后缀）	`/sse`

配置示例：

spring:
  ai:
    mcp:
      client:
        sse:
          connections:
            server1:
              url: http://localhost:8080
            server2:
              url: http://otherserver:8081
              sse-endpoint: /custom-sse

功能

同步/异步客户端类型

启动器支持两种类型的客户端：

同步 - 默认客户端类型，适用于具有阻塞操作的传统请求-响应模式
异步 - 适用于具有非阻塞操作的响应式应用程序，使用spring.ai.mcp.client.type=ASYNC配置

客户端自定义

自动配置通过回调接口提供广泛的客户端规范自定义功能。这些自定义器允许您配置MCP客户端行为的各个方面，从请求超时到事件处理和消息处理。

自定义类型

以下自定义选项可用：

请求配置 - 设置自定义请求超时
自定义采样处理器 - 服务器通过客户端向LLM请求LLM采样（completions或generations）的标准化方式。此流程允许客户端维护对模型访问、选择和权限的控制，同时使服务器能够利用AI功能——无需服务器API密钥。
文件系统（Roots）访问 - 客户端向服务器暴露文件系统roots的标准化方式。Roots定义了服务器可以在文件系统中操作的范围边界，使它们能够理解可以访问哪些目录和文件。服务器可以从支持的客户端请求roots列表，并在该列表更改时接收通知。
事件处理器 - 当发生某些服务器事件时要通知的客户端处理器：
- 工具变更通知 - 当可用服务器工具列表更改时
- 资源变更通知 - 当可用服务器资源列表更改时
- 提示变更通知 - 当可用服务器提示列表更改时
日志处理器 - 服务器向客户端发送结构化日志消息的标准化方式。客户端可以通过设置最小日志级别来控制日志详细程度

根据应用程序的需要，您可以为同步客户端实现McpSyncClientCustomizer，或为异步客户端实现McpAsyncClientCustomizer。

同步客户端自定义器

@Component
public class CustomMcpSyncClientCustomizer implements McpSyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.SyncSpec spec) {

        // 自定义请求超时配置
        spec.requestTimeout(Duration.ofSeconds(30));

        // 设置此客户端可以访问的根URI
        spec.roots(roots);

        // 设置用于处理消息创建请求的自定义采样处理器
        spec.sampling((CreateMessageRequest messageRequest) -> {
            // 处理采样
            CreateMessageResult result = ...
            return result;
        });

        // 添加一个消费者，在可用工具更改时（如工具被添加或删除时）被通知
        spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
            // 处理工具变更
        });

        // 添加一个消费者，在可用资源更改时（如资源被添加或删除时）被通知
        spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
            // 处理资源变更
        });

        // 添加一个消费者，在可用提示更改时（如提示被添加或删除时）被通知
        spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
            // 处理提示变更
        });

        // 添加一个消费者，在从服务器接收到日志消息时被通知
        spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
            // 处理日志消息
        });
    }
}

异步客户端自定义器

@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
        // 自定义异步客户端配置
        spec.requestTimeout(Duration.ofSeconds(30));
    }
}

serverConfigurationName参数是应用自定义器的服务器配置的名称，也是为其创建MCP客户端的名称。

MCP客户端自动配置会自动检测并应用在应用程序上下文中找到的任何自定义器。

传输支持

自动配置支持多种传输类型：

标准I/O（Stdio）（由spring-ai-starter-mcp-client激活）
SSE HTTP（由spring-ai-starter-mcp-client激活）
SSE WebFlux（由spring-ai-starter-mcp-client-webflux激活）

与Spring AI的集成

启动器可以配置与Spring AI工具执行框架集成的工具回调，允许MCP工具作为AI交互的一部分使用。此集成默认启用，可以通过设置spring.ai.mcp.client.toolcallback.enabled=false属性来禁用。

使用示例

将适当的启动器依赖项添加到您的项目中，并在application.properties或application.yml中配置客户端：

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: SYNC  # 或ASYNC用于响应式应用程序
        sse:
          connections:
            server1:
              url: http://localhost:8080
            server2:
              url: http://otherserver:8081
        stdio:
          root-change-notification: false
          connections:
            server1:
              command: /path/to/server
              args:
                - --port=8080
                - --mode=production
              env:
                API_KEY: your-api-key
                DEBUG: "true"

MCP客户端bean将被自动配置并可用于注入：

@Autowired
private List<McpSyncClient> mcpSyncClients;  // 用于同步客户端

// 或

@Autowired
private List<McpAsyncClient> mcpAsyncClients;  // 用于异步客户端

当启用工具回调时（默认行为），所有MCP客户端的注册MCP工具作为ToolCallbackProvider实例提供：

@Autowired
private SyncMcpToolCallbackProvider toolCallbackProvider;
ToolCallback[] toolCallbacks = toolCallbackProvider.getToolCallbacks();

示例应用程序

Brave网络搜索聊天机器人 - 一个使用模型上下文协议与网络搜索服务器交互的聊天机器人。
默认MCP客户端启动器 - 一个使用默认spring-ai-starter-mcp-client MCP客户端Boot启动器的简单示例。
WebFlux MCP客户端启动器 - 一个使用spring-ai-starter-mcp-client-webflux MCP客户端Boot启动器的简单示例。

9.1 MCP Client Boot Starter