MCP 客户端启动器

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

MCP 客户端启动器提供以下功能

  • 多客户端实例管理

  • 自动客户端初始化(如果启用)

  • 支持多种命名传输

  • 与 Spring AI 的工具执行框架集成

  • 适当的生命周期管理,并在应用上下文关闭时自动清理资源

  • 通过定制器实现可定制的客户端创建

启动器

Spring AI 自动配置和启动器模块的 artifact 名称发生了重大变化。请参考升级注意事项了解更多信息。

标准 MCP 客户端

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

标准启动器可以通过 STDIO(进程内)和/或 SSE(远程)传输同时连接到一个或多个 MCP 服务器。SSE 连接使用基于 HttpClient 的传输实现。每个与 MCP 服务器的连接都会创建一个新的 MCP 客户端实例。您可以选择 SYNCASYNC 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

客户端类型(SYNCASYNC)。所有客户端必须是同步或异步中的一种;不支持混合使用

SYNC

root-change-notification

对所有客户端启用/禁用根目录更改通知

true

toolcallback.enabled

启用/禁用 MCP 工具回调与 Spring AI 工具执行框架的集成

false

Stdio 传输属性

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

属性 描述 默认值

servers-configuration

包含 JSON 格式的 MCP 服务器配置的资源

-

connections

命名 stdio 连接配置的 Map

-

connections.[name].command

要为 MCP 服务器执行的命令

-

connections.[name].args

命令参数列表

-

connections.[name].env

服务器进程的环境变量 Map

-

配置示例

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"

或者,您可以使用外部 JSON 文件配置 stdio 连接,使用Claude Desktop 格式

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

Claude Desktop 格式如下所示

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

目前,Claude Desktop 格式仅支持 STDIO 连接类型。

SSE 传输属性

Server-Sent Events (SSE) 传输的属性以 spring.ai.mcp.client.sse 为前缀

属性 描述 默认值

connections

命名 SSE 连接配置的 Map

-

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 采样(completionsgenerations)的标准方式。此流程允许客户端保持对模型访问、选择和权限的控制,同时使服务器能够利用 AI 能力 — 无需服务器 API 密钥。

  • 文件系统(根目录)访问 - 客户端向服务器公开文件系统 roots 的标准方式。Roots 定义了服务器在文件系统中操作的边界,允许它们了解自己有权访问哪些目录和文件。服务器可以从支持的客户端请求 roots 列表,并在列表更改时接收通知。

  • 事件处理器 - 当发生特定服务器事件时通知客户端的处理器

    • 工具更改通知 - 当可用服务器工具列表更改时

    • 资源更改通知 - 当可用服务器资源列表更改时。

    • Prompts 更改通知 - 当可用服务器 prompts 列表更改时。

  • 日志处理器 - 服务器向客户端发送结构化日志消息的标准方式。客户端可以通过设置最低日志级别来控制日志详细程度

根据您的应用需求,您可以为同步客户端实现 McpSyncClientCustomizer,或为异步客户端实现 McpAsyncClientCustomizer

  • 同步

  • 异步

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

        // Customize the request timeout configuration
        spec.requestTimeout(Duration.ofSeconds(30));

        // Sets the root URIs that this client can access.
        spec.roots(roots);

        // Sets a custom sampling handler for processing message creation requests.
        spec.sampling((CreateMessageRequest messageRequest) -> {
            // Handle sampling
            CreateMessageResult result = ...
            return result;
        });

        // Adds a consumer to be notified when the available tools change, such as tools
        // being added or removed.
        spec.toolsChangeConsumer((List<McpSchema.Tool> tools) -> {
            // Handle tools change
        });

        // Adds a consumer to be notified when the available resources change, such as resources
        // being added or removed.
        spec.resourcesChangeConsumer((List<McpSchema.Resource> resources) -> {
            // Handle resources change
        });

        // Adds a consumer to be notified when the available prompts change, such as prompts
        // being added or removed.
        spec.promptsChangeConsumer((List<McpSchema.Prompt> prompts) -> {
            // Handle prompts change
        });

        // Adds a consumer to be notified when logging messages are received from the server.
        spec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
            // Handle log messages
        });
    }
}
@Component
public class CustomMcpAsyncClientCustomizer implements McpAsyncClientCustomizer {
    @Override
    public void customize(String serverConfigurationName, McpClient.AsyncSpec spec) {
        // Customize the async client configuration
        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 交互的一部分。此集成是可选加入的 (opt-in),并且必须通过设置属性 spring.ai.mcp.client.toolcallback.enabled=true 来显式启用。

使用示例

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

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-mcp-client
        version: 1.0.0
        request-timeout: 30s
        type: SYNC  # or ASYNC for reactive applications
        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;  // For sync client

// OR

@Autowired
private List<McpAsyncClient> mcpAsyncClients;  // For async client

当工具回调启用时,与所有 MCP 客户端注册的 MCP 工具将作为 ToolCallbackProvider 实例提供

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

请注意,工具回调功能默认是禁用的,必须通过以下方式显式启用

spring:
  ai:
    mcp:
      client:
        toolcallback:
          enabled: true

示例应用