MCP客户端启动器

Deepseek 3.2 中英对照 MCP Client Boot Starters MCP Client Boot Starter

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

MCP Client Boot Starter 提供以下功能：

• 多客户端实例管理

• 客户端自动初始化（如果启用）

• 支持多种命名传输方式（STDIO、Http/SSE 和可流式 HTTP）

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

• 工具筛选功能，用于选择性包含/排除工具

• 可自定义工具名称前缀生成，避免命名冲突

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

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

开胃菜

Standard MCP Client

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

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

WebFlux Client

WebFlux 启动器提供了与标准启动器类似的功能，但采用了基于 WebFlux 的 Streamable-Http、无状态 Streamable-Http 以及 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

MCP 注释属性

MCP客户端注解提供了一种使用Java注解实现MCP客户端处理程序的声明式方法。客户端mcp-annotations属性的前缀为spring.ai.mcp.client.annotation-scanner：

属性	描述	默认值
enabled	启用/禁用 MCP 客户端注解的自动扫描功能	true

标准输入输出传输属性

标准输入/输出传输的属性前缀为 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 Desktop格式的外部JSON文件来配置标准输入输出连接。

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"
      ]
    }
  }
}

Windows STDIO 配置

:::重要
在 Windows 系统中，诸如 npx、npm 和 node 之类的命令被实现为批处理文件 (.cmd)，而非原生可执行文件。Java 的 ProcessBuilder 无法直接执行批处理文件，需要使用 cmd.exe /c 包装器。
:::

为什么 Windows 需要特殊处理

当 Java 的 ProcessBuilder（由 StdioClientTransport 内部使用）尝试在 Windows 上启动进程时，它只能执行：

• 原生可执行文件 (.exe 文件)

• 可供 cmd.exe 使用的系统命令

Windows批处理文件，如npx.cmd、npm.cmd，甚至（来自Microsoft Store的）python.cmd，都需要cmd.exe shell才能执行。

解决方案：cmd.exe 包装器

使用 cmd.exe /c 包装批处理文件命令：

Windows 配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\username\\Desktop"
      ]
    }
  }
}

Linux/macOS 配置：

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

跨平台编程式配置

对于需要在跨平台环境中运行且无需独立配置文件的应用程序，可在您的Spring Boot应用中采用操作系统检测机制：

@Bean(destroyMethod = "close")
@ConditionalOnMissingBean(McpSyncClient.class)
public McpSyncClient mcpClient() {
    ServerParameters stdioParams;

    if (isWindows()) {
        // Windows: cmd.exe /c npx approach
        var winArgs = new ArrayList<>(Arrays.asList(
            "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "target"));
        stdioParams = ServerParameters.builder("cmd.exe")
                .args(winArgs)
                .build();
    } else {
        // Linux/Mac: direct npx approach
        stdioParams = ServerParameters.builder("npx")
                .args("-y", "@modelcontextprotocol/server-filesystem", "target")
                .build();
    }

    return McpClient.sync(new StdioClientTransport(stdioParams, McpJsonMapper.createDefault()))
            .requestTimeout(Duration.ofSeconds(10))
            .build()
            .initialize();
}

private static boolean isWindows() {
    return System.getProperty("os.name").toLowerCase().contains("win");
}

备注

使用 @Bean 进行程序化配置时，请添加 @ConditionalOnMissingBean(McpSyncClient.class) 注解，以避免与 JSON 文件的自动配置产生冲突。

路径考虑事项

相对路径（建议使用以确保可移植性）：

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "target"]
}

MCP服务器基于应用程序的工作目录解析相对路径。

绝对路径（Windows 要求使用反斜杠或转义的正斜杠）：

{
  "command": "cmd.exe",
  "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\username\\project\\target"]
}

需要 cmd.exe 的常见 Windows 批处理文件

• npx.cmd, npm.cmd - Node 包管理器

• python.cmd - Python（Microsoft Store 安装）

• pip.cmd - Python 包管理器

• mvn.cmd - Maven 包装器

• gradle.cmd - Gradle 包装器

• 自定义的 .cmd 或 .bat 脚本

参考实现

请参见 Spring AI Examples - Filesystem，这是一个完整的跨平台 MCP 客户端实现，能够自动检测操作系统并进行相应的客户端配置。

Streamable-HTTP 传输属性

用于连接 Streamable-HTTP 和 Stateless Streamable-HTTP MCP 服务器。

Streamable-HTTP 传输的属性前缀为 spring.ai.mcp.client.streamable-http：

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

示例配置：

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

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:
            # Simple configuration using default /sse endpoint
            server1:
              url: http://localhost:8080
            # Custom SSE endpoint
            server2:
              url: http://otherserver:8081
              sse-endpoint: /custom-sse
            # Complex URL with path and token (like MCP Hub)
            mcp-hub:
              url: http://localhost:3000
              sse-endpoint: /mcp-hub/sse/cf9ec4527e3c4a2cbb149a85ea45ab01
            # SSE endpoint with query parameters
            api-server:
              url: https://api.example.com
              sse-endpoint: /v1/mcp/events?token=abc123&format=json

URL 拆分指南

当你拥有一个完整的 SSE URL 时，将其拆分为基础 URL 和端点路径：

完整 URL	配置
http://localhost:3000/mcp-hub/sse/token123	url: [localhost:3000](http://localhost:3000) sse-endpoint: /mcp-hub/sse/token123
https://api.service.com/v2/events?key=secret	url: [api.service.com](https://api.service.com) sse-endpoint: /v2/events?key=secret
http://localhost:8080/sse	url: [localhost:8080](http://localhost:8080) sse-endpoint: /sse (或省略以使用默认值)

SSE连接故障排除

404 Not Found 错误：

• 验证URL拆分：确保基础 url 仅包含协议、主机和端口

• 检查 sse-endpoint 以 / 开头且包含完整的路径和查询参数

• 直接在浏览器或curl中测试完整的URL，以确认其可访问性

可流式传输的 HTTP 传输属性

Streamable Http 传输的属性前缀为 spring.ai.mcp.client.streamable-http：

属性	描述	默认值
connections	具名 Streamable Http 连接配置的映射	-
connections.[name].url	与 MCP 服务器进行 Streamable-Http 通信的基 URL 端点	-
connections.[name].endpoint	用于此连接的 streamable-http 端点 (作为 URL 后缀)	/mcp

示例配置：

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

功能特性

同步/异步客户端类型

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

• 同步 - 默认客户端类型 (spring.ai.mcp.client.type=SYNC)，适用于传统的请求-响应模式与阻塞操作

注意： SYNC 客户端仅会注册带有同步 MCP 注解的方法。异步方法将被忽略。

• 异步 - 适用于采用非阻塞操作的反应式应用程序，可通过配置 spring.ai.mcp.client.type=ASYNC 启用

注意： ASYNC 客户端仅会注册带有异步 MCP 注解的方法。同步方法将被忽略。

客户端自定义

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

定制类型

以下自定义选项可供选择：

• 请求配置 - 设置自定义请求超时

• 自定义采样处理器 - 服务器通过客户端向 LLM 请求采样（completions 或 generations）的标准方式。此流程允许客户端保持对模型访问、选择和权限的控制，同时使服务器能够利用 AI 能力——无需服务器 API 密钥。

• 文件系统（根目录）访问 - 客户端向服务器公开文件系统根目录的标准方式。根目录定义了服务器在文件系统中的操作边界，使其能够了解可以访问哪些目录和文件。服务器可以从支持此功能的客户端请求根目录列表，并在该列表发生变化时接收通知。

• 启发式处理器 - 服务器在交互过程中通过客户端向用户请求额外信息的标准方式。

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

  • 工具变更通知 - 当可用服务器工具列表发生变化时
  • 资源变更通知 - 当可用服务器资源列表发生变化时
  • 提示词变更通知 - 当可用服务器提示词列表发生变化时
  • 日志处理器 - 服务器向客户端发送结构化日志消息的标准方式。
  • 进度处理器 - 服务器向客户端发送结构化进度消息的标准方式。

客户端可以通过设置最低日志级别来控制日志的详细程度

客户端自定义示例

你可以根据应用程序的需求，实现 McpSyncClientCustomizer 用于同步客户端，或者 McpAsyncClientCustomizer 用于异步客户端。

Sync

@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;
        });

        // Sets a custom elicitation handler for processing elicitation requests.
        spec.elicitation((ElicitRequest request) -> {
          // handle elicitation
          return new ElicitResult(ElicitResult.Action.ACCEPT, Map.of("message", request.message()));
        });

        // Adds a consumer to be notified when progress notifications are received.
        spec.progressConsumer((ProgressNotification progress) -> {
         // Handle progress notifications
        });

        // 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
        });
    }
}

Async

@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客户端自动配置会自动检测并应用应用程序上下文中找到的所有自定义器。

传输支持

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

• 标准输入/输出（Stdio）（由 spring-ai-starter-mcp-client 和 spring-ai-starter-mcp-client-webflux 激活）

• （HttpClient）HTTP/SSE 与可流式 HTTP（由 spring-ai-starter-mcp-client 激活）

• （WebFlux）HTTP/SSE 与可流式 HTTP（由 spring-ai-starter-mcp-client-webflux 激活）

工具过滤

MCP 客户端启动器支持通过 McpToolFilter 接口对发现的工具进行过滤。这允许你根据自定义条件（例如 MCP 连接信息或工具属性）有选择地包含或排除工具。

要实现工具过滤，请创建一个实现 McpToolFilter 接口的 bean：

@Component
public class CustomMcpToolFilter implements McpToolFilter {

    @Override
    public boolean test(McpConnectionInfo connectionInfo, McpSchema.Tool tool) {
        // Filter logic based on connection information and tool properties
        // Return true to include the tool, false to exclude it

        // Example: Exclude tools from a specific client
        if (connectionInfo.clientInfo().name().equals("restricted-client")) {
            return false;
        }

        // Example: Only include tools with specific names
        if (tool.name().startsWith("allowed_")) {
            return true;
        }

        // Example: Filter based on tool description or other properties
        if (tool.description() != null &&
            tool.description().contains("experimental")) {
            return false;
        }

        return true; // Include all other tools by default
    }
}

McpConnectionInfo 记录提供以下内容的访问权限：

• clientCapabilities - MCP 客户端的能力

• clientInfo - 关于 MCP 客户端的信息（名称和版本）

• initializeResult - 来自 MCP 服务器的初始化结果

过滤器会自动检测并应用于同步和异步MCP工具回调提供程序。如果未提供自定义过滤器，默认情况下会包含所有已发现的工具。

注意：在应用上下文中只应定义一个 McpToolFilter Bean。如果需要多个过滤器，请将它们合并为一个复合过滤器实现。

工具名称前缀生成

MCP Client Boot Starter 支持通过 McpToolNamePrefixGenerator 接口实现可定制的工具名称前缀生成。该功能通过在工具名称前添加唯一前缀，有助于在集成多个 MCP 服务器的工具时避免命名冲突。

默认情况下，若未提供自定义的 McpToolNamePrefixGenerator 组件，启动器将使用 DefaultMcpToolNamePrefixGenerator，以确保所有 MCP 客户端连接中的工具名称具有唯一性。默认生成器：

• 跟踪所有现有连接和工具名称，以确保唯一性

• 通过将非字母数字字符替换为下划线来格式化工具名称（例如，my-tool 变为 my_tool）

• 当在不同连接中检测到重复的工具名称时，添加计数器前缀（例如，alt_1_toolName、alt_2_toolName）

• 线程安全且保持幂等性 —— 相同的（客户端、服务器、工具）组合始终获得相同的唯一名称

• 确保最终名称不超过 64 个字符（必要时从开头截断）

例如：

• 首次出现的工具 search → search
• 来自不同连接的第二次出现的工具 search → alt_1_search
• 包含特殊字符的工具 my-special-tool → my_special_tool

您可以通过提供自己的实现来定制此行为：

@Component
public class CustomToolNamePrefixGenerator implements McpToolNamePrefixGenerator {

    @Override
    public String prefixedToolName(McpConnectionInfo connectionInfo, Tool tool) {
        // Custom logic to generate prefixed tool names

        // Example: Use server name and version as prefix
        String serverName = connectionInfo.initializeResult().serverInfo().name();
        String serverVersion = connectionInfo.initializeResult().serverInfo().version();
        return serverName + "_v" + serverVersion.replace(".", "_") + "_" + tool.name();
    }
}

McpConnectionInfo 记录提供了有关 MCP 连接的全面信息：

• clientCapabilities - MCP 客户端的能力

• clientInfo - 关于 MCP 客户端的信息（名称、标题和版本）

• initializeResult - 来自 MCP 服务器的初始化结果，包括服务器信息

内置前缀生成器

该框架提供了多种内置的前缀生成器：

• DefaultMcpToolNamePrefixGenerator - 通过跟踪重复项并在需要时添加计数器前缀来确保工具名称的唯一性（如果未提供自定义 Bean，则默认使用此生成器）

• McpToolNamePrefixGenerator.noPrefix() - 返回不带任何前缀的工具名称（如果多个服务器提供同名的工具，可能导致冲突）

要完全禁用前缀并使用原始工具名称（如果在使用多个 MCP 服务器时不推荐这样做），请将 no-prefix 生成器注册为 bean：

@Configuration
public class McpConfiguration {

    @Bean
    public McpToolNamePrefixGenerator mcpToolNamePrefixGenerator() {
        return McpToolNamePrefixGenerator.noPrefix();
    }
}

前缀生成器通过Spring的ObjectProvider机制自动检测并应用于同步和异步MCP工具回调提供者。如果未提供自定义生成器bean，系统将自动使用DefaultMcpToolNamePrefixGenerator。

:::警告
当在多个MCP服务器中使用 McpToolNamePrefixGenerator.noPrefix() 时，重复的工具名称会导致 IllegalStateException。默认的 DefaultMcpToolNamePrefixGenerator 通过自动为重复的工具名称添加唯一前缀来防止这种情况。
:::

工具上下文到 MCP 元数据转换器

MCP Client Boot Starter 支持通过 ToolContextToMcpMetaConverter 接口，将 Spring AI 的 ToolContext 自定义转换为 MCP 工具调用元数据。此功能允许您将额外的上下文信息（例如用户 ID、密钥令牌）作为元数据，与 LLM 生成的调用参数一同传递。

例如，你可以将MCP progressToken 传递给你的MCP Progress Flow工具上下文，以跟踪长时间运行操作的进度：

ChatModel chatModel = ...

String response = ChatClient.create(chatModel)
        .prompt("Tell me more about the customer with ID 42")
        .toolContext(Map.of("progressToken", "my-progress-token"))
        .call()
        .content();

默认情况下，如果未提供自定义转换器 Bean，启动器将使用 ToolContextToMcpMetaConverter.defaultConverter()，该转换器：

• 过滤掉 MCP 交换密钥 (McpToolUtils.TOOL_CONTEXT_MCP_EXCHANGE_KEY)

• 过滤掉值为空的条目

• 将其余所有上下文条目作为元数据传递

您可以通过提供自己的实现来自定义此行为：

@Component
public class CustomToolContextToMcpMetaConverter implements ToolContextToMcpMetaConverter {

    @Override
    public Map<String, Object> convert(ToolContext toolContext) {
        if (toolContext == null || toolContext.getContext() == null) {
            return Map.of();
        }

        // Custom logic to convert tool context to MCP metadata
        Map<String, Object> metadata = new HashMap<>();

        // Example: Add custom prefix to all keys
        for (Map.Entry<String, Object> entry : toolContext.getContext().entrySet()) {
            if (entry.getValue() != null) {
                metadata.put("app_" + entry.getKey(), entry.getValue());
            }
        }

        // Example: Add additional metadata
        metadata.put("timestamp", System.currentTimeMillis());
        metadata.put("source", "spring-ai");

        return metadata;
    }
}

内置转换器

该框架提供了内置转换器：

• ToolContextToMcpMetaConverter.defaultConverter() - 过滤掉 MCP 交换键和空值（如果未提供自定义 bean，则默认使用此转换器）

• ToolContextToMcpMetaConverter.noOp() - 返回一个空映射，从而有效地禁用上下文到元数据的转换

要完全禁用上下文到元数据的转换：

@Configuration
public class McpConfiguration {

    @Bean
    public ToolContextToMcpMetaConverter toolContextToMcpMetaConverter() {
        return ToolContextToMcpMetaConverter.noOp();
    }
}

转换器会自动检测，并通过Spring的ObjectProvider机制应用于同步和异步MCP工具回调。如果未提供自定义转换器bean，则会自动使用默认转换器。

禁用 MCP ToolCallback 自动配置

MCP ToolCallback 自动配置默认启用，但可通过设置属性 spring.ai.mcp.client.toolcallback.enabled=false 来禁用。

当禁用时，不会从可用的 MCP 工具创建 ToolCallbackProvider 实例。

MCP 客户端注解

MCP Client Boot Starter 自动检测并注册带注解的方法，用于处理各种 MCP 客户端操作：

• @McpLogging - 处理来自 MCP 服务器的日志消息通知

• @McpSampling - 处理来自 MCP 服务器针对 LLM 补全的采样请求

• @McpElicitation - 处理引导请求，以从用户处收集额外信息

• @McpProgress - 处理长时间运行操作的状态通知

• @McpToolListChanged - 当服务器的工具列表变更时处理通知

• @McpResourceListChanged - 当服务器的资源列表变更时处理通知

• @McpPromptListChanged - 当服务器的提示词列表变更时处理通知

示例用法：

@Component
public class McpClientHandlers {

    @McpLogging(clients = "server1")
    public void handleLoggingMessage(LoggingMessageNotification notification) {
        System.out.println("Received log: " + notification.level() +
                          " - " + notification.data());
    }

    @McpSampling(clients = "server1")
    public CreateMessageResult handleSamplingRequest(CreateMessageRequest request) {
        // Process the request and generate a response
        String response = generateLLMResponse(request);

        return CreateMessageResult.builder()
            .role(Role.ASSISTANT)
            .content(new TextContent(response))
            .model("gpt-4")
            .build();
    }

    @McpProgress(clients = "server1")
    public void handleProgressNotification(ProgressNotification notification) {
        double percentage = notification.progress() * 100;
        System.out.println(String.format("Progress: %.2f%% - %s",
            percentage, notification.message()));
    }

    @McpToolListChanged(clients = "server1")
    public void handleToolListChanged(List<McpSchema.Tool> updatedTools) {
        System.out.println("Tool list updated: " + updatedTools.size() + " tools available");
        // Update local tool registry
        toolRegistry.updateTools(updatedTools);
    }
}

注解支持同步和异步两种实现方式，并可通过 clients 参数为特定客户端进行配置：

@McpLogging(clients = "server1")
public void handleServer1Logs(LoggingMessageNotification notification) {
    // Handle logs from specific server
    logToFile("server1.log", notification);
}

@McpSampling(clients = "server1")
public Mono<CreateMessageResult> handleAsyncSampling(CreateMessageRequest request) {
    return Mono.fromCallable(() -> {
        String response = generateLLMResponse(request);
        return CreateMessageResult.builder()
            .role(Role.ASSISTANT)
            .content(new TextContent(response))
            .model("gpt-4")
            .build();
    }).subscribeOn(Schedulers.boundedElastic());
}

有关所有可用注解及其使用模式的详细信息，请参阅 MCP 客户端注解 文档。

使用示例

将合适的启动器依赖项添加到项目中，并在 application.properties 或 application.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
        streamable-http:
          connections:
            server3:
              url: http://localhost:8083
              endpoint: /mcp
        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();

示例应用

• Brave 网络搜索聊天机器人 - 一个使用模型上下文协议（Model Context Protocol）与网络搜索服务器交互的聊天机器人。

• 默认 MCP 客户端 Starter - 使用默认的 spring-ai-starter-mcp-client MCP 客户端 Boot Starter 的简单示例。

• WebFlux MCP 客户端 Starter - 使用 spring-ai-starter-mcp-client-webflux MCP 客户端 Boot Starter 的简单示例。

额外资源

• Spring AI 文档

• 模型上下文协议规范

• Spring Boot 自动配置