最新快照版本请使用Spring AI 1.1.0spring-doc.cadn.net.cn

MCP 客户端启动Starters

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

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

首先

春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明spring-doc.cadn.net.cn

标准MCP客户端

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

标准Starters通过STDIO(处理中)和/或SSE(远程)传送。 SSE 连接采用基于 HttpClient 的传输实现。 每次连接到MCP服务器都会创建一个新的MCP客户端实例。 你可以选择其中任何一个同步异步MCP客户端(注意:不能混合使用同步和异步客户端)。 对于生产部署,我们建议使用基于WebFlux的SSE连接,配合Spring-AI-starter-mcp-client-webflux.spring-doc.cadn.net.cn

WebFlux客户端

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

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

配置属性

常见性质

常见的性质前缀为spring.ai.mcp.client:spring-doc.cadn.net.cn

属性 描述 默认值

启用spring-doc.cadn.net.cn

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

truespring-doc.cadn.net.cn

名称spring-doc.cadn.net.cn

MCP客户端实例名称spring-doc.cadn.net.cn

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

版本spring-doc.cadn.net.cn

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

1.0.0spring-doc.cadn.net.cn

初始 化spring-doc.cadn.net.cn

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

truespring-doc.cadn.net.cn

请求超时spring-doc.cadn.net.cn

MCP客户端请求的超时持续时间spring-doc.cadn.net.cn

20多岁spring-doc.cadn.net.cn

类型spring-doc.cadn.net.cn

客户端类型(同步或非同步)。所有客户端必须是同步或异步;不支持混合spring-doc.cadn.net.cn

同步spring-doc.cadn.net.cn

根变更通知spring-doc.cadn.net.cn

启用/禁用所有客户端的根更改通知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

Stdio交通资产

标准I/O传输的属性前缀为spring.ai.mcp.client.stdio:spring-doc.cadn.net.cn

属性 描述 默认值

服务器配置spring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接spring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接。[name].commandspring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接。[name].argsspring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接。[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"

或者,你也可以使用Claude Desktop格式的外部JSON文件配置stdio连接:spring-doc.cadn.net.cn

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

Claude 桌面格式如下:spring-doc.cadn.net.cn

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

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

SSE运输资产

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

属性 描述 默认值

连接spring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接。 [name].urlspring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

连接。 [name].sse-端点spring-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

特征

同步/异步客户端类型

起始程序支持两种客户端:spring-doc.cadn.net.cn

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

  • 异步——适合具有非阻塞作的响应式应用,配置为spring.ai.mcp.client.type=ASYNCspring-doc.cadn.net.cn

客户端定制

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

定制类型

以下可定制选项:spring-doc.cadn.net.cn

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

  • 自定义采样处理程序——服务器请求LLM采样的标准化方法 (完成生成)通过客户端从LLMs中获得。这种流程允许客户端保持对模型访问、选择和权限的控制,同时使服务器能够利用AI能力——无需服务器API密钥。spring-doc.cadn.net.cn

  • 文件系统(根)访问——客户端暴露文件系统的标准化方式对服务器。根节点定义了服务器在文件系统中可以运行的边界,使它们能够了解自己可以访问哪些目录和文件。服务器可以向支持的客户端请求根节点列表,并在该列表发生变化时收到通知。spring-doc.cadn.net.cn

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

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

你可以实现其中任何一种McpSyncClientCustomizer对于同步客户端或McpAsyncClientCustomizer对于异步客户端,取决于你的应用需求。spring-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

使用示例

给你的项目添加合适的起始依赖,并配置客户端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客户端豆子将自动配置并可供注入: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();

应用示例