此版本仍在开发中,尚不被认为是稳定的。对于最新的快照版本,请使用 Spring AI 1.0.1! |
MCP 客户端启动Starters
Spring AI MCP(模型上下文协议)客户端启动Starters为 Spring Boot 应用程序中的 MCP 客户端功能提供自动配置。 它支持具有各种传输选项的同步和异步客户端实现。
MCP 客户端Starters提供:
-
管理多个客户端实例
-
自动客户端初始化(如果启用)
-
支持多个命名传输(STDIO、Http/SSE 和可流式传输 HTTP)
-
与 Spring AI 的工具执行框架集成
-
适当的生命周期管理,在应用程序上下文关闭时自动清理资源
-
通过定制器创建可定制的客户端
首先
标准 MCP 客户端
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
标准Starters通过STDIO
(进程中),SSE
和Streamable Http
运输。
SSE 和 Streamable-Http 传输使用基于 JDK HttpClient 的传输实现。
与 MCP 服务器的每次连接都会创建一个新的 MCP 客户端实例。
您可以选择其中一种SYNC
或ASYNC
MCP 客户端(注意:不能混合使用同步客户端和异步客户端)。
对于生产部署,我们建议使用基于 WebFlux 的 SSE 和 StreamableHttp 连接以及spring-ai-starter-mcp-client-webflux
.
配置属性
共同属性
公共属性以spring.ai.mcp.client
:
属性 | 描述 | 默认值 |
---|---|---|
|
启用/禁用 MCP 客户端 |
|
|
MCP 客户端实例的名称 |
|
|
MCP 客户端实例的版本 |
|
|
是否在创建时初始化客户端 |
|
|
MCP 客户端请求的超时持续时间 |
|
|
客户端类型(SYNC 或 ASYNC)。所有客户端必须是同步或异步的;不支持混合 |
|
|
为所有客户端启用/禁用根更改通知 |
|
|
启用/禁用 MCP 工具回调与 Spring AI 的工具执行框架的集成 |
|
Stdio 传输属性
标准 I/O 传输的属性以spring.ai.mcp.client.stdio
:
属性 | 描述 | 默认值 |
---|---|---|
|
包含 JSON 格式的 MCP 服务器配置的资源 |
- |
|
命名 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 Desktop 格式仅支持 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
可流式传输 Http 传输属性
Streamable Http 传输的属性以spring.ai.mcp.client.streamable-http
:
属性 | 描述 | 默认值 |
---|---|---|
|
命名的可流式 Http 连接配置的映射 |
- |
|
用于与 MCP 服务器进行 Streamable-Http 通信的基本 URL 端点 |
- |
|
用于连接的 Streamable-HTTP 端点(作为 URL 后缀) |
|
配置示例:
spring:
ai:
mcp:
client:
streamable-http:
connections:
server1:
url: http://localhost:8080
server2:
url: http://otherserver:8081
endpoint: /custom-sse
特征
同步/异步客户端类型
Starters支持两种类型的客户端:
-
同步 - 默认客户端类型,适用于具有阻塞作的传统请求-响应模式
-
异步 - 适用于具有非阻塞作的响应式应用程序,使用
spring.ai.mcp.client.type=ASYNC
客户端定制
自动配置通过回调接口提供广泛的客户端规范自定义功能。这些定制器允许您配置 MCP 客户端行为的各个方面,从请求超时到事件处理和消息处理。
自定义类型
以下自定义选项可用:
-
请求配置 - 设置自定义请求超时
-
自定义采样处理程序 - 服务器请求 LLM 采样的标准化方式 (
completions
或generations
)通过客户端从 LLM 获取。此流程允许客户端保持对模型访问、选择和权限的控制,同时使服务器能够利用 AI 功能,而无需服务器 API 密钥。 -
文件系统(根)访问 - 客户端公开文件系统的标准化方式
roots
到服务器。根定义了服务器可以在文件系统中运行的边界,使它们能够了解他们有权访问哪些目录和文件。服务器可以向支持客户端请求根列表,并在该列表更改时接收通知。 -
激发处理程序 - 服务器在交互期间通过客户端向用户请求附加信息的标准化方式。
-
事件处理程序 - 当发生某个服务器事件时要通知的客户端处理程序:
-
工具更改通知 - 当可用服务器工具列表更改时
-
资源更改通知 - 当可用服务器资源列表发生更改时。
-
提示更改通知 - 当可用服务器列表提示更改时。
-
日志记录处理程序 - 服务器向客户端发送结构化日志消息的标准化方式。
-
客户端可以通过设置最低日志级别来控制日志详细程度
您可以实现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;
});
// 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
});
}
}
@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
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 Web Search 聊天机器人 - 使用模型上下文协议与 Web 搜索服务器交互的聊天机器人。
-
默认 MCP 客户端Starters - 使用默认
spring-ai-starter-mcp-client
MCP 客户端启动Starters。 -
WebFlux MCP 客户端入门 - 使用
spring-ai-starter-mcp-client-webflux
MCP 客户端启动Starters。