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

1. 概述STDIO和SSE MCP服务端支持多种传输机制每种机制对应专用的启动器。使用STDIO客户端或SSE客户端即可连接对应的服务端。2. 启动器类型2.1 STDIO MCP Server完整的MCP服务端功能基于STDIO传输。dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server/artifactId/dependency特点适用于命令行和桌面工具无需额外的Web依赖支持基础服务端组件配置支持工具、资源、提示词声明处理支持服务端能力管理与变更通知同时支持同步(SYNC)和异步(ASYNC)实现2.2 SSE WebMVC Server完整的MCP服务端功能基于Spring MVC的SSEServer-Sent Events传输可选配STDIO传输。dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webmvc/artifactId/dependency特点基于Spring MVC的HTTP传输WebMvcSseServerTransportProvider自动配置SSE端点可选STDIO传输设置spring.ai.mcp.server.stdiotrue启用包含spring-boot-starter-web和mcp-spring-webmvc依赖2.3 SSE WebFlux Server完整的MCP服务端功能基于Spring WebFlux的 SSE 传输可选配STDIO传输。dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webflux/artifactId/dependency该启动器激活McpWebFluxServerAutoConfiguration和McpServerAutoConfiguration自动配置提供基于Spring WebFlux的响应式传输WebFluxSseServerTransportProvider自动配置响应式SSE端点可选STDIO传输设置spring.ai.mcp.server.stdiotrue启用包含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配置项说明默认值enabled开启/关闭 MCP 服务端truetool-callback-converter开启/关闭 Spring AI ToolCallback 到 MCP Tool 声明的自动转换truestdio开启/关闭 STDIO 传输falsename服务端标识名称mcp-serverversion服务端版本1.0.0instructions可选的服务使用指引用于告知客户端如何与此服务端交互nulltype服务端类型SYNC(同步) / ASYNC(异步)SYNCcapabilities.resource开启/关闭资源能力truecapabilities.tool开启/关闭工具能力truecapabilities.prompt开启/关闭提示词能力truecapabilities.completion开启/关闭补全能力trueresource-change-notification开启资源变更通知trueprompt-change-notification开启提示词变更通知truetool-change-notification开启工具变更通知truetool-response-mime-type按工具名配置响应 MIME 类型。例如spring.ai.mcp.server.tool-response-mime-type.generateImageimage/png将image/png与generateImage()工具关联-request-timeout请求超时时间适用于工具调用、资源访问、提示词操作等所有客户端请求20s3.2 MCP 注解配置MCP服务端注解提供了一种声明式方式使用Java注解来实现MCP服务端处理器。配置前缀spring.ai.mcp.server.annotation-scanner配置项说明默认值enabled开启/关闭 MCP 服务端注解自动扫描true3.3 SSE 配置配置前缀spring.ai.mcp.server出于向后兼容考虑SSE 属性没有额外的后缀如.sse。配置项说明默认值sse-message-endpoint自定义 SSE 消息端点路径供客户端发送消息/mcp/messagesse-endpoint自定义 SSE 端点路径/ssebase-url可选的 URL 前缀。例如base-url/api/v1表示客户端应访问/api/v1sse-endpoint消息端点为/api/v1sse-message-endpoint-keep-alive-interval连接保活间隔null禁用4. 功能与能力MCP Server Boot Starter允许服务端向客户端暴露工具、资源、提示词并自动将注册为Spring Bean的自定义能力处理器转换为对应的同步/异步声明。4.1 工具Tools允许服务端暴露可供语言模型调用的工具。提供以下特性变更通知支持Spring AI工具根据服务端类型自动转换为同步/异步声明通过Spring Bean自动注册工具声明高级 API 注册方式BeanpublicToolCallbackProvidermyTools(...){ListToolCallbacktools...returnToolCallbackProvider.from(tools);}底层 API 注册方式BeanpublicListMcpServerFeatures.SyncToolSpecificationmyTools(...){ListMcpServerFeatures.SyncToolSpecificationtools...returntools;}自动配置会检测并注册以下来源的所有工具回调单个ToolCallbackBeanToolCallback列表BeanToolCallbackProviderBean工具按名称去重重名工具以首次出现的为准。设置tool-callback-converterfalse可禁用自动检测与注册。4.1.1 工具上下文支持支持ToolContext可将上下文信息传递给工具调用。上下文在exchange键下包含一个McpSyncServerExchange实例可通过McpToolUtils.getMcpExchange(toolContext)访问用于调用exchange.loggingNotification(…)和exchange.createMessage(…)等方法。4.2 资源Resources以标准化方式向客户端暴露资源。提供以下特性静态和动态资源声明可选的变更通知资源模板支持同步/异步资源声明自动转换注册方式BeanpublicListMcpServerFeatures.SyncResourceSpecificationmyResources(...){varsystemInfoResourcenewMcpSchema.Resource(...);varresourceSpecificationnewMcpServerFeatures.SyncResourceSpecification(systemInfoResource,(exchange,request)-{try{varsystemInfoMap.of(...);StringjsonContentnewObjectMapper().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以标准化方式向客户端暴露提示词模板。提供以下特性变更通知支持模板版本管理同步/异步提示词声明自动转换注册方式BeanpublicListMcpServerFeatures.SyncPromptSpecificationmyPrompts(){varpromptnewMcpSchema.Prompt(greeting,A friendly greeting prompt,List.of(newMcpSchema.PromptArgument(name,The name to greet,true)));varpromptSpecificationnewMcpServerFeatures.SyncPromptSpecification(prompt,(exchange,getPromptRequest)-{StringnameArgument(String)getPromptRequest.arguments().get(name);if(nameArgumentnull){nameArgumentfriend;}varuserMessagenewPromptMessage(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以标准化方式向客户端暴露自动补全能力。支持同步和异步补全声明。注册方式BeanpublicListMcpServerFeatures.SyncCompletionSpecificationmyCompletions(){varcompletionnewMcpServerFeatures.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());}客户端可注册进度消费者来更新UImcpClientSpec.progressConsumer((McpSchema.ProgressNotificationprogress)-{// 处理进度通知});4.7 根路径变更Root List Changes当根路径发生变化时支持listChanged的客户端会发送根路径变更通知。支持监控根路径变化自动转换为异步消费者以适配响应式应用通过Spring Bean可选注册BeanpublicBiConsumerMcpSyncServerExchange,ListMcpSchema.RootrootsChangeHandler(){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:30s5. 使用示例5.1 STDIO 服务端配置# 使用 spring-ai-starter-mcp-serverspring:ai:mcp:server:name:stdio-mcp-serverversion:1.0.0type:SYNC5.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 resourcescapabilities:tool:trueresource:trueprompt:truecompletion:truesse-message-endpoint:/mcp/messageskeep-alive-interval:30s5.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 resourcescapabilities:tool:trueresource:trueprompt:truecompletion:truesse-message-endpoint:/mcp/messageskeep-alive-interval:30s5.4 创建 MCP 服务端应用ServicepublicclassWeatherService{Tool(description根据城市名称获取天气信息)publicStringgetWeather(StringcityName){// 实现逻辑}}SpringBootApplicationpublicclassMcpServerApplication{privatestaticfinalLoggerloggerLoggerFactory.getLogger(McpServerApplication.class);publicstaticvoidmain(String[]args){SpringApplication.run(McpServerApplication.class,args);}BeanpublicToolCallbackProviderweatherTools(WeatherServiceweatherService){returnMethodToolCallbackProvider.builder().toolObjects(weatherService).build();}}自动配置会将工具回调自动注册为MCP工具。你可以有多个生成ToolCallbacks的Bean自动配置会自动合并它们。