|
最新快照版本请使用Spring AI 1.1.0! |
MCP 客户端启动Starters
Spring AI MCP(模型上下文协议)客户端启动Starters为 Spring Boot 应用中的 MCP 客户端功能提供自动配置。它支持同步和异步客户端实现,并支持多种传输选项。
MCP 客户端启动Starters提供:
-
多客户端实例管理
-
自动客户端初始化(如果启用的话)
-
多命名运输的支持
-
与 Spring AI 工具执行框架的集成
-
当应用上下文关闭时,实现正确的生命周期管理,自动清理资源
-
通过自定义工具实现可定制的客户端创建
首先
|
春季AI自动配置、起始模块的工件名称发生了重大变化。 更多信息请参阅升级说明。 |
标准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.ai.mcp.client:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
启用/禁用MCP客户端 |
|
|
MCP客户端实例名称 |
|
|
MCP 客户端实例的版本 |
|
|
是否在创建时初始化客户端 |
|
|
MCP客户端请求的超时持续时间 |
|
|
客户端类型(同步或非同步)。所有客户端必须是同步或异步;不支持混合 |
|
|
启用/禁用所有客户端的根更改通知 |
|
|
启用/禁用MCP工具回调与Spring AI工具执行框架的集成 |
|
Stdio交通资产
标准I/O传输的属性前缀为spring.ai.mcp.client.stdio:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
包含 MCP 服务器配置的 JSON 格式资源 |
- |
|
命名stdio连接配置的映射 |
- |
|
MCP服务器执行命令 |
- |
|
命令参数列表 |
- |
|
服务器进程环境变量映射 |
- |
示例配置:
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:
ai:
mcp:
client:
stdio:
servers-configuration: classpath:mcp-servers.json
Claude 桌面格式如下:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/username/Desktop",
"/Users/username/Downloads"
]
}
}
}
目前,Claude桌面格式仅支持STDIO连接类型。
SSE运输资产
服务器发送事件(SSE)传输的属性前缀为spring.ai.mcp.client.sse:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
命名SSE连接配置映射 |
- |
|
用于与MCP服务器的SSE通信的基础URL端点 |
- |
|
连接时使用的SSE端点(作为URL后缀) |
|
示例配置:
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采样的标准化方法 (
完成或生成)通过客户端从LLMs中获得。这种流程允许客户端保持对模型访问、选择和权限的控制,同时使服务器能够利用AI能力——无需服务器API密钥。 -
文件系统(根)访问——客户端暴露文件系统的标准化方式
根对服务器。根节点定义了服务器在文件系统中可以运行的边界,使它们能够了解自己可以访问哪些目录和文件。服务器可以向支持的客户端请求根节点列表,并在该列表发生变化时收到通知。 -
事件处理程序——客户端处理程序,在特定服务器事件发生时被通知:
-
工具变更通知——当可用服务器工具列表发生变化时
-
资源变更通知——当可用服务器资源列表发生变化时。
-
提示变更通知——当可用服务器提示列表发生变化时。
-
-
日志处理程序——服务器向客户端发送结构化日志消息的标准化方式。客户端可以通过设置最低日志级别来控制日志冗长度
你可以实现其中任何一种McpSyncClientCustomizer对于同步客户端或McpAsyncClientCustomizer对于异步客户端,取决于你的应用需求。
-
Sync
-
Async
@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客户端自动配置会自动检测并应用应用上下文中的任何自定义器。
使用示例
给你的项目添加合适的起始依赖,并配置客户端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
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客户端豆子将自动配置并可供注入:
@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 Web Search 聊天机器人——一款使用 Model Context 协议与网络搜索服务器交互的聊天机器人。
-
默认MCP客户端Starters——使用默认的简单示例
Spring-AI-starter-mcp-clientMCP 客户端启动Starters。 -
WebFlux MCP 客户端Starters——使用
Spring-AI-starter-mcp-client-webfluxMCP 客户端启动Starters。