Spring AI MCP客户端Boot Starter 是为Spring Boot应用提供 MCP（Model Context Protocol）客户端自动配置 的组件，核心支持 STDIO（进程内）、SSE（远程）、SSE WebFlux 三种传输协议，提供 SYNC（默认）/ASYNC 两种客户端类型，具备 多实例管理、自动初始化、生命周期管理、Spring AI工具执行框架集成 等核心功能，可通过配置文件灵活定义连接参数，支持通过定制器自定义客户端行为，适用于需与MCP服务器交互的AI应用（如聊天机器人）。

一、核心定位与整体功能

Spring AI MCP客户端Boot Starter 旨在为Spring Boot应用简化MCP（Model Context Protocol）客户端的配置与使用，提供以下核心能力：

• 多客户端实例管理：支持同时连接1个或多个MCP服务器，每个连接对应独立客户端实例
• 自动化能力：自动初始化（默认启用）、应用上下文关闭时自动清理资源
• 灵活扩展：支持传输协议切换、客户端类型选择、自定义行为配置
• 生态集成：默认与Spring AI工具执行框架集成，MCP工具可作为AI交互组件

二、Starter类型与依赖配置

Starter类型	依赖坐标	核心支持
标准MCP Client	org.springframework.ai:spring-ai-starter-mcp-client	传输协议：STDIO（进程内）、SSE（基于HttpClient）；支持SYNC/ASYNC客户端
WebFlux客户端	org.springframework.ai:spring-ai-starter-mcp-client-webflux	传输协议：SSE WebFlux（非阻塞）；功能与标准Starter一致，适配响应式应用

注意：生产环境推荐使用WebFlux客户端（SSE WebFlux传输）；不可混合使用SYNC与ASYNC客户端。

三、关键配置属性（按前缀分类）

1. 公共属性（前缀：spring.ai.mcp.client）

属性名	说明	默认值
enabled	启用/禁用MCP客户端	true
name	客户端实例名称（用于兼容性检查）	spring-ai-mcp-client
version	客户端实例版本	1.0.0
initialized	创建时是否自动初始化客户端	true
request-timeout	请求超时时长	20s
type	客户端类型（SYNC/ASYNC），不可混合使用	SYNC
root-change-notification	启用所有客户端的root变更通知	true
toolcallback.enabled	启用MCP工具回调与Spring AI工具执行框架的集成	true

2. Stdio传输属性（前缀：spring.ai.mcp.client.stdio）

属性名	说明	默认值
servers-configuration	包含MCP服务器配置的JSON资源文件（如classpath:mcp-servers.json）	-
connections	命名的Stdio连接配置Map	-
connections.[name].command	MCP服务器的执行命令	-
connections.[name].args	命令参数列表	-
connections.[name].env	服务器进程的环境变量Map	-

spring:
  ai:
    mcp:
      client:
        request-timeout: 360s
        stdio:
          servers-configuration: classpath:/config/mcp-servers-config-4.json

{
  "mcpServers": {
    "mcp-server-csdn": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/Users/fuzhengwei/Applications/apache-maven-3.8.4/repository/cn/bugstack/mcp/mcp-server-csdn/1.0.0/mcp-server-csdn-1.0.0.jar",
        "--csdn.api.categories=Java场景面试宝典",
        "--csdn.api.cookie=dc_sid=4f39db19db5e07b3712c8252f5192a49; fid=20_68843256053-1742793553663-285430; uuid_tt_dd=11_60528736741-1742793553664-565742; dc_session_id=11_1742793553664.859940; c_first_ref=default; c_first_page=https%3A//editor.csdn.net/md/%3Fnot_checkout%3D1%26userType%3D0%26spm%3D1011.2648.3001.9829; c_dsid=11_1742793553665.665235; c_segment=14; loginbox_strategy=%7B%22taskId%22%3A349%2C%22abCheckTime%22%3A1742793553990%2C%22version%22%3A%22exp11%22%7D; SESSION=ccc78ccb-de15-44ab-91f2-b2d00c2f3bc2; Hm_lvt_6bcd52f51e9b3dce32bec4a3997715ac=1742793554; HMACCOUNT=D3F21FD70412F10D; creative_btn_mp=1; hide_login=1; UserName=weixin_46755643; UserInfo=a5fd907efac34d68b004a0379558af09; UserToken=a5fd907efac34d68b004a0379558af09; UserNick=%E5%B0%8F%E5%82%85%E5%93%A5%E7%9A%84%E7%A0%81%E4%BB%94; AU=1C3; UN=weixin_46755643; BT=1742793567470; p_uid=U010000; csdn_newcert_weixin_46755643=1; creativeSetApiNew=%7B%22toolbarImg%22%3A%22https%3A//img-home.csdnimg.cn/images/20231011044944.png%22%2C%22publishSuccessImg%22%3A%22https%3A//img-home.csdnimg.cn/images/20240229024608.png%22%2C%22articleNum%22%3A0%2C%22type%22%3A0%2C%22oldUser%22%3Afalse%2C%22useSeven%22%3Atrue%2C%22oldFullVersion%22%3Afalse%2C%22userName%22%3A%22weixin_46755643%22%7D; c_page_id=default; _clck=v0bde0%7C2%7Cfuh%7C0%7C1909; _clsk=1uer2f6%7C1742793628405%7C1%7C0%7Cw.clarity.ms%2Fcollect; __gads=ID=197e0e0e1df8b355:T=1742793628:RT=1742793628:S=ALNI_MZo-ICXVKtTuru1eWKmPwbg3iFBEA; __gpi=UID=0000107082bfa689:T=1742793628:RT=1742793628:S=ALNI_MZo_6EqfVmGZhBBxv_U6kDuuAdBlw; __eoi=ID=c492eef37ae294b0:T=1742793628:RT=1742793628:S=AA-AfjYXHpnUExkGioah07nXY2Ar; FCNEC=%5B%5B%22AKsRol-sUSV75OeG9zcvrFfuHb1yXHx-Ci3fbXucnvqgLdCKtzceyQ3mniDL3FEHCWK5rjyz-lBSGGQKyLh98QioO4NmCYZxmV95edZOk8TxSuORPwiMmdv9ulw2hjxrLGWNhlAPN73cJiplTNBmBUtSv07sf8m6bg%3D%3D%22%5D%5D; c_pref=https%3A//editor.csdn.net/; c_ref=https%3A//mp.csdn.net/mp_blog/creation/success/146473915; log_Id_pv=12; Hm_lpvt_6bcd52f51e9b3dce32bec4a3997715ac=1742793721; dc_tos=stm48s; log_Id_view=325; log_Id_click=22"
      ]
    },
    "mcp-server-weixin": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/Users/fuzhengwei/Applications/apache-maven-3.8.4/repository/cn/bugstack/mcp/mcp-server-weixin/1.0.0/mcp-server-weixin-1.0.0.jar"
      ]
    }
  }
}

3. SSE传输属性（前缀：spring.ai.mcp.client.sse）

属性名	说明	默认值
connections	命名的SSE连接配置Map	-
connections.[name].url	SSE通信的Base URL端点	-
connections.[name].sse-endpoint	SSE连接端点（URL后缀）	/sse

spring:
  ai:
    mcp:
      client:
        request-timeout: 360s
        sse:
          connections:
            mcp-server-csdn:
              url: http://127.0.0.1:8101
            mcp-server-weixin:
              url: http://127.0.0.1:8102

四、核心特性详解

1. 客户端类型（二选一，不可混合）

• SYNC（同步）：默认类型，适用于传统阻塞式请求-响应场景，配置简单直接。
• ASYNC（异步）：适用于非阻塞响应式应用，需通过spring.ai.mcp.client.type=ASYNC配置，适配WebFlux等响应式框架。

2. 自定义客户端能力

通过实现McpSyncClientCustomizer（同步）或McpAsyncClientCustomizer（异步）接口，可自定义以下行为：

• 请求配置：修改请求超时（默认20s，示例改为30s）。
• 采样Handler：处理LLM采样请求（补全/生成），客户端掌控模型访问权限。
• 根目录访问：设置服务器可访问的文件系统根目录，支持根目录变更通知。
• 事件Handler：接收工具变更、资源变更、提示词变更通知。
• 日志Handler：处理服务器发送的结构化日志，支持按级别过滤。

3. 传输协议支持

传输协议	依赖Starter	适用场景	核心特点
STDIO	标准Starter	进程内MCP服务器交互	基于命令执行，配置简单
SSE HTTP	标准Starter	远程MCP服务器（阻塞式）	基于HttpClient，支持多连接
SSE WebFlux	WebFlux Starter	远程MCP服务器（非阻塞式）	适配响应式应用，生产环境推荐

4. Spring AI集成

• 集成状态：默认启用（toolcallback.enabled=true），可通过配置禁用。
• 集成效果：MCP工具自动注册为Spring AI工具，通过SyncMcpToolCallbackProvider获取ToolCallback实例，直接用于AI模型的工具调用。

五、用例与示例应用

1. 典型用例：与MCP服务器交互的AI应用（如Web搜索聊天机器人、工具调用类AI服务）。
2. 配置示例：支持在application.yml/application.properties中直接配置连接，或通过外部JSON文件（Claude Desktop格式）配置Stdio连接。
3. 官方示例：

• • Brave Web Search Chatbot：与Web搜索服务器交互的聊天机器人。
  • Default MCP Client Starter：标准Starter的基础使用示例。
  • WebFlux MCP Client Starter：WebFlux Starter的响应式示例。