Spring AI 1.x 系列【43】基于标准输入输出 (STDIO) 与服务端推送事件 (SSE) 的 MCP 服务端

1. 概述

STDIO和SSE MCP服务端支持多种传输机制，每种机制对应专用的启动器。使用STDIO客户端或SSE客户端即可连接对应的服务端。

2. 启动器类型

2.1 STDIO MCP Server

完整的MCP服务端功能，基于STDIO传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server</artifactId></dependency>

特点：

• 适用于命令行和桌面工具
• 无需额外的Web依赖
• 支持基础服务端组件配置
• 支持工具、资源、提示词声明处理
• 支持服务端能力管理与变更通知
• 同时支持同步(SYNC)和异步(ASYNC)实现

2.2 SSE WebMVC Server

完整的MCP服务端功能，基于Spring MVC的SSE（Server-Sent Events）传输，可选配STDIO传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webmvc</artifactId></dependency>

特点：

• 基于Spring MVC的HTTP传输（WebMvcSseServerTransportProvider）
• 自动配置SSE端点
• 可选STDIO传输（设置spring.ai.mcp.server.stdio=true启用）
• 包含spring-boot-starter-web和mcp-spring-webmvc依赖

2.3 SSE WebFlux Server

完整的MCP服务端功能，基于Spring WebFlux的 SSE 传输，可选配STDIO传输。

<dependency><groupId>org.springframework.ai</groupId><artifactId>spring-ai-starter-mcp-server-webflux</artifactId></dependency>

该启动器激活McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration自动配置，提供：

• 基于Spring WebFlux的响应式传输（WebFluxSseServerTransportProvider）
• 自动配置响应式SSE端点
• 可选STDIO传输（设置spring.ai.mcp.server.stdio=true启用）
• 包含spring-boot-starter-webflux和mcp-spring-webflux依赖

注意：根据 Spring Boot 默认行为，当 classpath 上同时存在org.springframework.web.servlet.DispatcherServlet和org.springframework.web.reactive.DispatcherHandler时，Spring Boot 会优先使用DispatcherServlet。因此，如果你的项目使用了spring-boot-starter-web，建议使用spring-ai-starter-mcp-server-webmvc而非 WebFlux 版本。

3. 配置项说明

3.1 通用配置

配置前缀：spring.ai.mcp.server

3.2 MCP 注解配置

MCP服务端注解提供了一种声明式方式，使用Java注解来实现MCP服务端处理器。

配置前缀：spring.ai.mcp.server.annotation-scanner

3.3 SSE 配置

配置前缀：spring.ai.mcp.server

出于向后兼容考虑，SSE 属性没有额外的后缀（如.sse）。

4. 功能与能力

MCP Server Boot Starter允许服务端向客户端暴露工具、资源、提示词，并自动将注册为Spring Bean的自定义能力处理器转换为对应的同步/异步声明。

4.1 工具（Tools）

允许服务端暴露可供语言模型调用的工具。提供以下特性：

• 变更通知支持
• Spring AI工具根据服务端类型自动转换为同步/异步声明
• 通过Spring Bean自动注册工具声明

高级 API 注册方式：

@BeanpublicToolCallbackProvidermyTools(...){List<ToolCallback>tools=...returnToolCallbackProvider.from(tools);}

底层 API 注册方式：

@BeanpublicList<McpServerFeatures.SyncToolSpecification>myTools(...){List<McpServerFeatures.SyncToolSpecification>tools=...returntools;}

自动配置会检测并注册以下来源的所有工具回调：

• 单个ToolCallbackBean
• ToolCallback列表Bean
• ToolCallbackProviderBean

工具按名称去重，重名工具以首次出现的为准。设置tool-callback-converter=false可禁用自动检测与注册。

4.1.1 工具上下文支持

支持ToolContext，可将上下文信息传递给工具调用。上下文在exchange键下包含一个McpSyncServerExchange实例，可通过McpToolUtils.getMcpExchange(toolContext)访问，用于调用exchange.loggingNotification(…)和exchange.createMessage(…)等方法。

4.2 资源（Resources）

以标准化方式向客户端暴露资源。提供以下特性：

• 静态和动态资源声明
• 可选的变更通知
• 资源模板支持
• 同步/异步资源声明自动转换

注册方式：

@BeanpublicList<McpServerFeatures.SyncResourceSpecification>myResources(...){varsystemInfoResource=newMcpSchema.Resource(...);varresourceSpecification=newMcpServerFeatures.SyncResourceSpecification(systemInfoResource,(exchange,request)->{try{varsystemInfo=Map.of(...);StringjsonContent=newObjectMapper().writeValueAsString(systemInfo);returnnewMcpSchema.ReadResourceResult(List.of(newMcpSchema.TextResourceContents(request.uri(),"application/json",jsonContent)));}catch(Exceptione){thrownewRuntimeException("Failed to generate system info",e);}});returnList.of(resourceSpecification);}

4.3 提示词（Prompts）

以标准化方式向客户端暴露提示词模板。提供以下特性：

• 变更通知支持
• 模板版本管理
• 同步/异步提示词声明自动转换

注册方式：

@BeanpublicList<McpServerFeatures.SyncPromptSpecification>myPrompts(){varprompt=newMcpSchema.Prompt("greeting","A friendly greeting prompt",List.of(newMcpSchema.PromptArgument("name","The name to greet",true)));varpromptSpecification=newMcpServerFeatures.SyncPromptSpecification(prompt,(exchange,getPromptRequest)->{StringnameArgument=(String)getPromptRequest.arguments().get("name");if(nameArgument==null){nameArgument="friend";}varuserMessage=newPromptMessage(Role.USER,newTextContent("Hello "+nameArgument+"! How can I assist you today?"));returnnewGetPromptResult("A personalized greeting message",List.of(userMessage));});returnList.of(promptSpecification);}

4.4 补全（Completions）

以标准化方式向客户端暴露自动补全能力。支持同步和异步补全声明。

注册方式：

@BeanpublicList<McpServerFeatures.SyncCompletionSpecification>myCompletions(){varcompletion=newMcpServerFeatures.SyncCompletionSpecification(newMcpSchema.PromptReference("ref/prompt","code-completion","Provides code completion suggestions"),(exchange,request)->{returnnewMcpSchema.CompleteResult(List.of("python","pytorch","pyside"),10,true);});returnList.of(completion);}

4.5 日志（Logging）

以标准化方式向客户端发送结构化日志消息。在工具、资源、提示词或补全的调用处理器中，使用McpSyncServerExchange/McpAsyncServerExchange对象发送日志：

(exchange,request)->{exchange.loggingNotification(LoggingMessageNotification.builder().level(LoggingLevel.INFO).logger("test-logger").data("This is a test log message").build());}

客户端侧可注册日志消费者来处理这些消息：

mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotificationlog)->{// 处理日志消息});

4.6 进度（Progress）

以标准化方式向客户端发送进度更新。在工具、资源、提示词或补全的调用处理器中，使用McpSyncServerExchange/McpAsyncServerExchange对象发送进度通知：

(exchange,request)->{exchange.progressNotification(ProgressNotification.builder().progressToken("test-progress-token").progress(0.25).total(1.0).message("tool call in progress").build());}

客户端可注册进度消费者来更新UI：

mcpClientSpec.progressConsumer((McpSchema.ProgressNotificationprogress)->{// 处理进度通知});

4.7 根路径变更（Root List Changes）

当根路径发生变化时，支持listChanged的客户端会发送根路径变更通知。

• 支持监控根路径变化
• 自动转换为异步消费者以适配响应式应用
• 通过Spring Bean可选注册

@BeanpublicBiConsumer<McpSyncServerExchange,List<McpSchema.Root>>rootsChangeHandler(){return(exchange,roots)->{logger.info("Registering root resources: {}",roots);};}

4.8 心跳（Ping）

服务端用于验证客户端是否仍在线的机制。在工具、资源、提示词或补全的调用处理器中，使用McpSyncServerExchange/McpAsyncServerExchange发送心跳：

(exchange,request)->{exchange.ping();}

4.9 保活（Keep Alive）

服务端可定期向已连接的客户端发送心跳以验证连接健康状态。默认禁用，通过以下配置启用：

spring:ai:mcp:server:keep-alive-interval:30s

5. 使用示例

5.1 STDIO 服务端配置

# 使用 spring-ai-starter-mcp-serverspring:ai:mcp:server:name:stdio-mcp-serverversion:1.0.0type:SYNC

5.2 WebMVC 服务端配置

# 使用 spring-ai-starter-mcp-server-webmvcspring:ai:mcp:server:name:webmvc-mcp-serverversion:1.0.0type:SYNCinstructions:"This server provides weather information tools and resources"capabilities:tool:trueresource:trueprompt:truecompletion:truesse-message-endpoint:/mcp/messageskeep-alive-interval:30s

5.3 WebFlux 服务端配置

# 使用 spring-ai-starter-mcp-server-webfluxspring:ai:mcp:server:name:webflux-mcp-serverversion:1.0.0type:ASYNC# 响应式应用推荐使用 ASYNCinstructions:"This reactive server provides weather information tools and resources"capabilities:tool:trueresource:trueprompt:truecompletion:truesse-message-endpoint:/mcp/messageskeep-alive-interval:30s

5.4 创建 MCP 服务端应用

@ServicepublicclassWeatherService{@Tool(description="根据城市名称获取天气信息")publicStringgetWeather(StringcityName){// 实现逻辑}}@SpringBootApplicationpublicclassMcpServerApplication{privatestaticfinalLoggerlogger=LoggerFactory.getLogger(McpServerApplication.class);publicstaticvoidmain(String[]args){SpringApplication.run(McpServerApplication.class,args);}@BeanpublicToolCallbackProviderweatherTools(WeatherServiceweatherService){returnMethodToolCallbackProvider.builder().toolObjects(weatherService).build();}}

自动配置会将工具回调自动注册为MCP工具。你可以有多个生成ToolCallbacks的Bean，自动配置会自动合并它们。