Spring AI 1.x 系列【45】无状态流式 HTTP 类型 MCP 服务端

1. 概述无状态StatelessStreamable-HTTP MCP服务端专为简化部署而设计请求之间不维护会话状态非常适合微服务架构和云原生部署场景。启用方式设置spring.ai.mcp.server.protocolSTATELESS并使用 Streamable-HTTP 客户端连接。限制无状态服务端不支持向 MCP 客户端发起的消息请求如 elicitation、sampling、ping 等。2. 启动器类型2.1 Stateless WebMVC Server使用spring-ai-starter-mcp-server-webmvc依赖并设置spring.ai.mcp.server.protocolSTATELESS。dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webmvc/artifactId/dependency特点基于Spring MVC传输的无状态运行模式无会话状态管理简化的部署模型针对云原生环境优化2.2 Stateless WebFlux Server使用spring-ai-starter-mcp-server-webflux依赖并设置spring.ai.mcp.server.protocolSTATELESS。dependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-mcp-server-webflux/artifactId/dependency特点基于WebFlux传输的响应式无状态运行模式无会话状态管理非阻塞请求处理针对高吞吐场景优化3. 配置项说明3.1 通用配置配置前缀spring.ai.mcp.server配置项说明默认值enabled开启/关闭无状态 MCP 服务端trueprotocolMCP 服务端协议必须设为 STATELESS-tool-callback-converter开启/关闭 Spring AI ToolCallback 到 MCP Tool 声明的自动转换truename服务端标识名称mcp-serverversion服务端版本1.0.0instructions可选的客户端交互指引nulltype服务端类型SYNC(同步) / ASYNC(异步)SYNCcapabilities.resource开启/关闭资源能力truecapabilities.tool开启/关闭工具能力truecapabilities.prompt开启/关闭提示词能力truecapabilities.completion开启/关闭补全能力truetool-response-mime-type按工具名配置响应 MIME 类型-request-timeout请求超时时间20s注意无状态服务端不支持变更通知resource-change-notification / tool-change-notification / prompt-change-notification因此通用配置中不包含这些项。3.2 MCP 注解配置配置前缀spring.ai.mcp.server.annotation-scanner配置项说明默认值enabled开启/关闭 MCP 服务端注解自动扫描true3.3 Stateless 连接配置配置前缀spring.ai.mcp.server.stateless配置项说明默认值mcp-endpoint自定义 MCP 端点路径/mcpdisallow-delete禁止 DELETE 操作false4. 功能与能力MCP Server Boot Starter会自动将注册为Spring Bean的自定义能力处理器转换为对应的同步/异步声明。与有状态服务端的关键区别无状态服务端使用的 API 类为McpStatelessServerFeatures非McpServerFeatures且不支持McpSyncServerExchange/McpAsyncServerExchange上下文对象。4.1 工具Tools允许服务端暴露可供语言模型调用的工具。提供以下特性变更通知支持Spring AI工具根据服务端类型自动转换为同步/异步声明通过Spring Bean自动注册工具声明高级 API 注册方式BeanpublicToolCallbackProvidermyTools(...){ListToolCallbacktools...returnToolCallbackProvider.from(tools);}底层 API 注册方式BeanpublicListMcpStatelessServerFeatures.SyncToolSpecificationmyTools(...){ListMcpStatelessServerFeatures.SyncToolSpecificationtools...returntools;}自动配置会检测并注册以下来源的所有工具回调单个ToolCallbackBeanToolCallback列表BeanToolCallbackProviderBean工具按名称去重重名工具以首次出现的为准。设置tool-callback-converterfalse可禁用自动检测与注册。注意工具上下文支持Tool Context Support不适用于无状态服务端。4.2 资源Resources以标准化方式向客户端暴露资源。提供以下特性静态和动态资源声明可选的变更通知资源模板支持同步/异步资源声明自动转换注册方式BeanpublicListMcpStatelessServerFeatures.SyncResourceSpecificationmyResources(...){varsystemInfoResourcenewMcpSchema.Resource(...);varresourceSpecificationnewMcpStatelessServerFeatures.SyncResourceSpecification(systemInfoResource,(context,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以标准化方式向客户端暴露提示词模板。提供以下特性变更通知支持模板版本管理同步/异步提示词声明自动转换注册方式BeanpublicListMcpStatelessServerFeatures.SyncPromptSpecificationmyPrompts(){varpromptnewMcpSchema.Prompt(greeting,A friendly greeting prompt,List.of(newMcpSchema.PromptArgument(name,The name to greet,true)));varpromptSpecificationnewMcpStatelessServerFeatures.SyncPromptSpecification(prompt,(context,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以标准化方式向客户端暴露自动补全能力。支持同步和异步补全声明。BeanpublicListMcpStatelessServerFeatures.SyncCompletionSpecificationmyCompletions(){varcompletionnewMcpStatelessServerFeatures.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);}5. 使用示例5.1 Stateless 服务端配置spring:ai:mcp:server:protocol:STATELESSname:stateless-mcp-serverversion:1.0.0type:ASYNCinstructions:This stateless server is optimized for cloud deploymentsstateless:mcp-endpoint:/api/mcp5.2 创建 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工具。支持多个Bean分别生成ToolCallbacks自动配置会自动合并它们。