STDIO 和 SSE MCP 服务器
STDIO 和 SSE MCP 服务器支持多种传输机制,每种机制都有专用的Starters。
STDIO MCP 服务器
完整的MCP服务器功能支持STDIO服务器运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>
-
适用于命令行和桌面工具
-
无需额外的网络依赖
-
基本服务器组件配置
-
工具、资源和提示符规格的处理
-
服务器能力管理和变更通知
-
支持同步和异步服务器实现
SSE WebMVC 服务器
完整的MCP服务器功能支持SSE(服务器发送事件)基于 Spring MVC 的服务器传输,并可选STDIO运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
-
基于HTTP的Spring MVC传输(
WebMvcSseServerTransportProvider) -
自动配置的SSE终端
-
自选
STDIO传输(通过设置启用)spring.ai.mcp.server.stdio=true) -
包括
Spring Boot启动网和MCP-Spring-webmvc依赖
SSE WebFlux 服务器
完整的MCP服务器功能支持SSE(服务器发送事件)基于 Spring WebFlux 的服务器传输,并可选STDIO运输。
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
Starters会激活McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration自动配置以提供:
-
使用Spring WebFlux的无效传输(
WebFluxSseServerTransportProvider) -
自动配置的响应式SSE端点
-
自选
STDIO传输(通过设置启用)spring.ai.mcp.server.stdio=true) -
包括
Spring BootStarters网流和MCP-Spring-Webflux依赖
|
由于 Spring Boot 的默认行为,当两者 |
配置属性
常见性质
所有 Common 属性前缀为spring.ai.mcp.server:
| 属性 | 描述 | 默认值 |
|---|---|---|
|
启用/禁用MCP服务器 |
|
|
启用/禁用将 Spring AI ToolCallback 转换为 MCP 工具规范 |
|
|
启用/禁用STDIO传输 |
|
|
用于识别的服务器名称 |
|
|
服务器版本 |
|
|
可选指令,指导客户端如何与该服务器交互 |
|
|
服务器类型(同步/非同步) |
|
|
启用/禁用资源功能 |
|
|
启用/禁用工具功能 |
|
|
启用/禁用提示符功能 |
|
|
启用/禁用完成功能 |
|
|
启用资源变更通知 |
|
|
启用即时变更通知 |
|
|
启用刀具更换通知 |
|
|
可选响应 MIME 类型,按工具名称。例如 |
|
|
等待服务器响应的时间长,然后在超时请求。适用于通过客户端发出的所有请求,包括工具调用、资源访问和提示作 |
|
功能与功能
MCP 服务器启动Starters允许服务器向客户端暴露工具、资源和提示符。它自动将注册为 Spring Beans 的自定义能力处理程序转换为基于服务器类型的同步/异步规范:
工具
允许服务器公开可被语言模型调用的工具。MCP 服务器启动Starters提供:
-
变更通知支持
-
Spring AI 工具会自动根据服务器类型转换为同步/非同步规范
-
通过春季豆自动工具配置:
@Bean
public ToolCallbackProvider myTools(...) {
List<ToolCallback> tools = ...
return ToolCallbackProvider.from(tools);
}
或者使用底层 API:
@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
List<McpServerFeatures.SyncToolSpecification> tools = ...
return tools;
}
自动配置会自动检测并注册来自以下所有工具回调:
-
个人
工具回调豆 -
列表
工具回调豆 -
ToolCallbackProvider豆
工具按名称进行重复处理,每个工具名称首次出现的顺序被使用。
你可以通过设置工具回调转换器自false. |
工具上下文支持
支持ToolContext,允许将上下文信息传递给工具调用。它包含McpSyncServerExchange实例在交换钥匙,可通过以下方式访问McpToolUtils.getMcpExchange(toolContext). 请看这个示例exchange.loggingNotification(...)和exchange.createMessage(...).
资源
为服务器向客户端暴露资源提供了标准化方式。
-
静态与动态资源规范
-
可选变更通知
-
资源模板支持
-
同步/异步资源规格之间的自动转换
-
通过春季豆自动资源分配:
@Bean
public List<McpServerFeatures.SyncResourceSpecification> myResources(...) {
var systemInfoResource = new McpSchema.Resource(...);
var resourceSpecification = new McpServerFeatures.SyncResourceSpecification(systemInfoResource, (exchange, request) -> {
try {
var systemInfo = Map.of(...);
String jsonContent = new ObjectMapper().writeValueAsString(systemInfo);
return new McpSchema.ReadResourceResult(
List.of(new McpSchema.TextResourceContents(request.uri(), "application/json", jsonContent)));
}
catch (Exception e) {
throw new RuntimeException("Failed to generate system info", e);
}
});
return List.of(resourceSpecification);
}
提示
为服务器提供了一种标准化的方式,以向客户端展示提示模板。
-
变更通知支持
-
模板版本管理
-
同步/异步提示符规格之间的自动转换
-
通过Spring Beans自动提示指定:
@Bean
public List<McpServerFeatures.SyncPromptSpecification> myPrompts() {
var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));
var promptSpecification = new McpServerFeatures.SyncPromptSpecification(prompt, (exchange, getPromptRequest) -> {
String nameArgument = (String) getPromptRequest.arguments().get("name");
if (nameArgument == null) { nameArgument = "friend"; }
var userMessage = new PromptMessage(Role.USER, new TextContent("Hello " + nameArgument + "! How can I assist you today?"));
return new GetPromptResult("A personalized greeting message", List.of(userMessage));
});
return List.of(promptSpecification);
}
完成
为服务器提供一种标准化的方式,将完成功能暴露给客户端。
-
支持同步和异步完成规范
-
通过春豆自动注册:
@Bean
public List<McpServerFeatures.SyncCompletionSpecification> myCompletions() {
var completion = new McpServerFeatures.SyncCompletionSpecification(
new McpSchema.PromptReference(
"ref/prompt", "code-completion", "Provides code completion suggestions"),
(exchange, request) -> {
// Implementation that returns completion suggestions
return new McpSchema.CompleteResult(List.of("python", "pytorch", "pyside"), 10, true);
}
);
return List.of(completion);
}
Logging
为服务器向客户端发送结构化日志消息提供了标准化方式。在工具、资源、提示符或完成调用处理器中,可以使用提供的McpSyncServerExchange/McpAsyncServerExchange 交换发送日志消息的对象:
(exchange, request) -> {
exchange.loggingNotification(LoggingMessageNotification.builder()
.level(LoggingLevel.INFO)
.logger("test-logger")
.data("This is a test log message")
.build());
}
在MCP客户端上,你可以注册日志消费者以处理以下消息:
mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
// Handle log messages
});
进展
为服务器提供向客户端发送进度更新的标准化方式。在工具、资源、提示符或完成调用处理器内部,可以使用提供的McpSyncServerExchange/McpAsyncServerExchange 交换发送进度通知的对象:
(exchange, request) -> {
exchange.progressNotification(ProgressNotification.builder()
.progressToken("test-progress-token")
.progress(0.25)
.total(1.0)
.message("tool call in progress")
.build());
}
Mcp客户端可以接收进度通知并相应更新其UI。为此,它需要注册一个进度消费者。
mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
// Handle progress notifications
});
根列表变更
当根源改变时,支持的客户端列表已更改发送根更更通知。
-
支持监控根变更
-
为被动应用自动转换为异步消费者
-
可选择通过Spring Beans注册
@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
return (exchange, roots) -> {
logger.info("Registering root resources: {}", roots);
};
}
乒
服务器验证客户端仍然存活的ping机制。在工具、资源、提示符或完成调用处理器内,使用提供的McpSyncServerExchange/McpAsyncServerExchange 交换发送ping消息的对象:
(exchange, request) -> {
exchange.ping();
}
使用示例
标准STDIO服务器配置
# Using spring-ai-starter-mcp-server
spring:
ai:
mcp:
server:
name: stdio-mcp-server
version: 1.0.0
type: SYNC
WebMVC 服务器配置
# Using spring-ai-starter-mcp-server-webmvc
spring:
ai:
mcp:
server:
name: webmvc-mcp-server
version: 1.0.0
type: SYNC
instructions: "This server provides weather information tools and resources"
capabilities:
tool: true
resource: true
prompt: true
completion: true
# sse properties
sse-message-endpoint: /mcp/messages
keep-alive-interval: 30s
WebFlux 服务器配置
# Using spring-ai-starter-mcp-server-webflux
spring:
ai:
mcp:
server:
name: webflux-mcp-server
version: 1.0.0
type: ASYNC # Recommended for reactive applications
instructions: "This reactive server provides weather information tools and resources"
capabilities:
tool: true
resource: true
prompt: true
completion: true
# sse properties
sse-message-endpoint: /mcp/messages
keep-alive-interval: 30s
创建带有MCP服务器的Spring Boot应用程序
@Service
public class WeatherService {
@Tool(description = "Get weather information by city name")
public String getWeather(String cityName) {
// Implementation
}
}
@SpringBootApplication
public class McpServerApplication {
private static final Logger logger = LoggerFactory.getLogger(McpServerApplication.class);
public static void main(String[] args) {
SpringApplication.run(McpServerApplication.class, args);
}
@Bean
public ToolCallbackProvider weatherTools(WeatherService weatherService) {
return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
}
}
自动配置会自动将工具回调注册为MCP工具。你可以有多个豆子生成ToolCallback,自动配置会将它们合并。
应用示例
-
天气服务器(WebFlux)——春季 AI MCP 服务器启动Starters,支持 WebFlux 传输
-
天气服务器(STDIO)——支持 STDIO 传输的 Spring AI MCP 服务器启动Starters
-
Weather Server 手动配置 - Spring AI MCP 服务器启动Starters,不使用自动配置,而是使用 Java SDK 手动配置服务器