获取最新的快照版本,请使用 Spring AI 1.1.3spring-doc.cadn.net.cn

MCP客户端启动Starters

Spring Boot中的MCP模型上下文协议(Model Context Protocol)客户Starters提供自动配置MCP客户端功能的实现。该Starters支持同步和异步客户端实现,并提供多种传输选项。spring-doc.cadn.net.cn

MCP 客户端Starters提供:spring-doc.cadn.net.cn

Starters

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。spring-doc.cadn.net.cn

标准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-webfluxspring-doc.cadn.net.cn

WebFlux 客户端

WebFlux starter 提供了与标准 starter 类似的功能,但使用基于 WebFlux 的 SSE 传输实现。spring-doc.cadn.net.cn

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

配置属性

常见属性

常见的属性都以0前缀表示:spring-doc.cadn.net.cn

属性 描述 默认值

enabledspring-doc.cadn.net.cn

启用/禁用 MCP 客户端spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

namespring-doc.cadn.net.cn

mcpClientNamespring-doc.cadn.net.cn

spring-ai-mcp-clientspring-doc.cadn.net.cn

versionspring-doc.cadn.net.cn

MCP客户端实例的版本号spring-doc.cadn.net.cn

1.0.0spring-doc.cadn.net.cn

initializedspring-doc.cadn.net.cn

是否在创建时初始化客户端spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

request-timeoutspring-doc.cadn.net.cn

MCP客户端请求的超时时间设置。spring-doc.cadn.net.cn

20sspring-doc.cadn.net.cn

typespring-doc.cadn.net.cn

客户端类型必须是SYNC或ASYNC。所有客户端必须是SYNC或ASYNC,混合使用不被支持。spring-doc.cadn.net.cn

SYNCspring-doc.cadn.net.cn

root-change-notificationspring-doc.cadn.net.cn

所有客户端启用或禁用root变更通知spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

toolcallback.enabledspring-doc.cadn.net.cn

启用或禁用MCP工具回调集成,与Spring AI的工具执行框架结合。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

Spring框架运输属性

标准I/O传输的属性以0前缀:spring-doc.cadn.net.cn

属性 描述 默认值

servers-configurationspring-doc.cadn.net.cn

包含MCP服务器配置的JSON格式的资源spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connectionsspring-doc.cadn.net.cn

命名文件句柄连接配置地图spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connections.[name].commandspring-doc.cadn.net.cn

用于MCP服务器的执行命令spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connections.[name].argsspring-doc.cadn.net.cn

命令参数列表spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connections.[name].envspring-doc.cadn.net.cn

服务器过程的环境变量地图spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

示例配置:spring-doc.cadn.net.cn

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文件(采用Claude Desktop格式)来配置stdio连接:spring-doc.cadn.net.cn

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

Claude Desktop 格式如下所示:spring-doc.cadn.net.cn

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

目前,Claude Desktop 格式仅支持 STDIO 连接类型。spring-doc.cadn.net.cn

SSE 传输属性

服务器发送事件(SSE)传输的属性以 spring.ai.mcp.client.sse 开头:spring-doc.cadn.net.cn

属性 描述 默认值

connectionsspring-doc.cadn.net.cn

命名的SSE连接配置映射spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connections.[name].urlspring-doc.cadn.net.cn

与MCP服务器进行SSE通信的基础URL端点spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

connections.[name].sse-endpointspring-doc.cadn.net.cn

用于连接的 SSE 端点(作为 URL 后缀)spring-doc.cadn.net.cn

/ssespring-doc.cadn.net.cn

示例配置:spring-doc.cadn.net.cn

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

特性

同步/异步客户端类型

该Starters支持两种类型的客户端:spring-doc.cadn.net.cn

  • 同步 - 默认客户端类型,适用于具有阻塞操作的传统请求-响应模式。spring-doc.cadn.net.cn

  • 异步 - 适用于具有非阻塞操作的响应式应用程序,通过使用 spring.ai.mcp.client.type=ASYNC 进行配置spring-doc.cadn.net.cn

客户端自定义

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

自定义类型

以下自定义选项可用:spring-doc.cadn.net.cn

  • 请求配置 - 设置自定义请求超时spring-doc.cadn.net.cn

  • 自定义采样处理器 - 服务器通过客户端向大语言模型请求采样(completionsgenerations)的标准化方式。该流程允许客户端在维持对模型访问、选择和权限控制的同时,使服务器能够利用人工智能能力——且无需服务器API密钥。spring-doc.cadn.net.cn

  • 文件系统(根目录)访问 - 客户端向服务器公开文件系统 roots 的标准化方式。 根目录定义了服务器在文件系统中可操作的边界,使其能够了解可以访问哪些目录和文件。 服务器可以向支持的客户端请求根目录列表,并在该列表发生变化时接收通知。spring-doc.cadn.net.cn

  • 事件处理器 - 当特定服务器事件发生时,通知客户端处理器:spring-doc.cadn.net.cn

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

您可以根据应用程序的需要,为同步客户端实现 McpSyncClientCustomizer,或为异步客户端实现 McpAsyncClientCustomizerspring-doc.cadn.net.cn

@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 客户端的名称。spring-doc.cadn.net.cn

MCP 客户端自动配置会自动检测并应用应用程序上下文中找到的任何自定义器。spring-doc.cadn.net.cn

传输支持

自动配置支持多种传输类型:spring-doc.cadn.net.cn

与Spring AI集成

入门项目可以配置与 Spring AI 的工具执行框架集成的工具回调,从而允许将 MCP 工具用作 AI 交互的一部分。此集成默认启用,可通过设置 spring.ai.mcp.client.toolcallback.enabled=false 属性来禁用。spring-doc.cadn.net.cn

使用示例

将适当的Starters依赖项添加到您的项目中,并在 application.propertiesapplication.yml 中配置客户端:spring-doc.cadn.net.cn

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 将会自动配置并可供注入:spring-doc.cadn.net.cn

@Autowired
private List<McpSyncClient> mcpSyncClients;  // For sync client

// OR

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

当启用工具回调(默认行为)时,所有MCP客户端注册的MCP工具将作为一个 ToolCallbackProvider 实例提供:spring-doc.cadn.net.cn

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

示例应用程序