Spring AI MCP 依赖配置指南
# Spring AI MCP 依赖配置指南
重要提示: Spring AI MCP Boot Starter模块的artifact名称发生了重大变化。请参考官方升级说明 (opens new window)获取更多信息。
# 📦 正确的依赖配置
# MCP服务器 (Server)
# 1. WebMVC SSE传输 (推荐用于Web应用)
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
1
2
3
4
2
3
4
特性：
- ✅ 基于Spring MVC的SSE传输
- ✅ 自动配置SSE端点(
/sse) - ✅ 自动配置消息端点(
/mcp/message) - ✅ 可选STDIO传输支持
- ✅ 包含
spring-boot-starter-web
# 2. WebFlux SSE传输 (响应式应用)
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
1
2
3
4
2
3
4
# 3. STDIO传输 (命令行工具)
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>
1
2
3
4
2
3
4
# MCP客户端 (Client)
# 1. 标准HTTP客户端 (推荐)
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>
1
2
3
4
2
3
4
特性：
- ✅ 支持STDIO和SSE传输
- ✅ 基于HttpClient的SSE实现
- ✅ 自动MCP客户端管理
- ✅ 自动工具回调集成
- ✅ 同步/异步支持
# 2. WebFlux客户端 (生产推荐)
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>
1
2
3
4
2
3
4
# ⚙️ 配置属性详解
# 服务器配置 (spring.ai.mcp.server)
spring:
ai:
mcp:
server:
# 基础配置
enabled: true # 启用/禁用MCP服务器
name: mcp-server-demo # 服务器名称
version: 1.0.0 # 服务器版本
type: SYNC # 服务器类型 (SYNC/ASYNC)
# 端点配置
sse-endpoint: /sse # SSE端点路径
sse-message-endpoint: /mcp/message # 消息端点路径
base-url: /api/v1 # URL前缀 (可选)
# 功能配置
capabilities:
tool: true # 工具能力
resource: true # 资源能力
prompt: true # 提示能力
completion: true # 完成能力
# 通知配置
tool-change-notification: true # 工具变更通知
resource-change-notification: true # 资源变更通知
prompt-change-notification: true # 提示变更通知
# 高级配置
stdio: false # STDIO传输 (WebMVC/WebFlux可选)
request-timeout: 20s # 请求超时
instructions: "服务器使用说明" # 客户端使用指导
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 客户端配置 (spring.ai.mcp.client)
spring:
ai:
mcp:
client:
# 基础配置
enabled: true # 启用/禁用MCP客户端
name: spring-ai-mcp-client # 客户端名称
version: 1.0.0 # 客户端版本
type: SYNC # 客户端类型 (SYNC/ASYNC)
initialized: true # 创建时是否初始化
request-timeout: 20s # 请求超时
root-change-notification: true # 根目录变更通知
# 工具集成
toolcallback:
enabled: true # 启用Spring AI工具集成
# SSE连接配置
sse:
connections:
demo-server: # 连接名称
url: http://localhost:9099 # 服务器URL
sse-endpoint: /sse # SSE端点 (默认/sse)
other-server:
url: http://otherhost:8080
sse-endpoint: /custom-sse
# STDIO连接配置 (可选)
stdio:
connections:
local-server:
command: /path/to/server
args:
- --port=8080
- --mode=production
env:
API_KEY: your-api-key
DEBUG: "true"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 🔧 自动配置特性
# 服务器自动配置
- ✅ 自动端点注册: 无需手动创建Controller
- ✅ 工具自动发现:
@Tool注解的方法自动注册 - ✅ 类型转换: Spring AI工具自动转换为MCP规范
- ✅ 生命周期管理: 自动启动/停止服务器
# 客户端自动配置
- ✅ 自动Bean创建:
McpSyncClient/McpAsyncClient自动注入 - ✅ 工具回调集成:
SyncMcpToolCallbackProvider自动配置 - ✅ 连接管理: 自动连接/重连/清理
- ✅ 错误处理: 自动重试和故障恢复
# 📝 最简配置示例
# 服务器最简配置
@SpringBootApplication
public class McpServerApplication {
public static void main(String[] args) {
SpringApplication.run(McpServerApplication.class, args);
}
@Bean
public ToolCallbackProvider demoTools() {
return ToolCallbackProvider.from(
new CalculatorTool() // 自动转换为MCP工具
);
}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
# application.yml
spring:
ai:
mcp:
server:
name: demo-server
1
2
3
4
5
6
2
3
4
5
6
# 客户端最简配置
@SpringBootApplication
public class McpClientApplication {
@Autowired
private List<McpSyncClient> mcpClients; // 自动注入
@Autowired
private SyncMcpToolCallbackProvider toolProvider; // 自动工具集成
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# application.yml
spring:
ai:
mcp:
client:
sse:
connections:
demo-server:
url: http://localhost:9099
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
# ⚠️ 迁移注意事项
# 常见错误
- ❌ 使用
spring-ai-mcp而非spring-ai-starter-mcp-client - ❌ 手动创建SSE端点
- ❌ 混用SYNC和ASYNC客户端
- ❌ 配置属性格式错误
# 🔗 官方参考资源
上次更新: 2025/06/06, 11:28:26