|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Stateless Streamable-HTTP MCP Servers
Stateless Streamable-HTTP MCP servers are designed for simplified deployments where session state is not maintained between requests. These servers are ideal for microservices architectures and cloud-native deployments.
Set the spring.ai.mcp.server.protocol=STATELESS property
|
| Use the Streamable-HTTP clients to connect to the stateless servers. |
| The stateless servers don’t support message requests to the MCP client (e.g., elicitation, sampling, ping). |
Stateless WebMVC Server
Use the spring-ai-starter-mcp-server-webmvc dependency:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>
and set the spring.ai.mcp.server.protocol property to STATELESS.
spring.ai.mcp.server.protocol=STATELESS
-
Stateless operation with Spring MVC transport
-
No session state management
-
Simplified deployment model
-
Optimized for cloud-native environments
Stateless WebFlux Server
Use the spring-ai-starter-mcp-server-webflux dependency:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>
and set the spring.ai.mcp.server.protocol property to STATELESS.
-
Reactive stateless operation with WebFlux transport
-
No session state management
-
Non-blocking request processing
-
Optimized for high-throughput scenarios
Configuration Properties
Common Properties
All Common properties are prefixed with spring.ai.mcp.server:
| Property | Description | Default |
|---|---|---|
|
Enable/disable the stateless MCP server |
|
|
MCP server protocol |
Must be set to |
|
Enable/disable the conversion of Spring AI ToolCallbacks into MCP Tool specs |
|
|
Server name for identification |
|
|
Server version |
|
|
Optional instructions for client interaction |
|
|
Server type (SYNC/ASYNC) |
|
|
Enable/disable resource capabilities |
|
|
Enable/disable tool capabilities |
|
|
Enable/disable prompt capabilities |
|
|
Enable/disable completion capabilities |
|
|
Whether to re-expose downstream MCP tools (provided by MCP clients) as tools in this MCP server |
|
|
Response MIME type per tool name |
|
|
Request timeout duration |
|
MCP Annotations Properties
MCP Server Annotations provide a declarative way to implement MCP server handlers using Java annotations.
The server mcp-annotations properties are prefixed with spring.ai.mcp.server.annotation-scanner:
| Property | Description | Default Value |
|---|---|---|
|
Enable/disable the MCP server annotations auto-scanning |
|
Stateless Connection Properties
The stateless transports read their endpoint from the Streamable-HTTP properties, prefixed with spring.ai.mcp.server.streamable-http:
| Property | Description | Default |
|---|---|---|
|
Custom MCP endpoint path |
|
The other Streamable-HTTP properties, keep-alive-interval and disallow-delete, do not apply to the stateless transports.
Features and Capabilities
The MCP Server Boot Starter allows servers to expose tools, resources, and prompts to clients. It automatically converts custom capability handlers registered as Spring beans to sync/async specifications based on the server type.
A stateless server sends no list-changed notifications.
It does not advertise listChanged for tools, resources or prompts, and the *-change-notification properties do not apply to it.
|
Tools
Allows servers to expose tools that can be invoked by language models. The MCP Server Boot Starter provides:
-
Spring AI Tools are automatically converted to sync/async specifications based on the server type
-
Automatic tool specification through Spring beans:
@Bean
public ToolCallbackProvider myTools(...) {
List<ToolCallback> tools = ...
return ToolCallbackProvider.from(tools);
}
or using the low-level API:
@Bean
public List<McpStatelessServerFeatures.SyncToolSpecification> myTools(...) {
List<McpStatelessServerFeatures.SyncToolSpecification> tools = ...
return tools;
}
The auto-configuration will automatically detect and register all tool callbacks from:
-
Individual
ToolCallbackbeans -
Lists of
ToolCallbackbeans -
ToolCallbackProviderbeans
Tools are de-duplicated by name, with the first occurrence of each tool name being used.
You can disable the automatic detection and registration of all tool callbacks by setting the tool-callback-converter to false.
|
| Tool Context Support is not applicable for stateless servers. |
Resources
Provides a standardized way for servers to expose resources to clients.
-
Static and dynamic resource specifications
-
Support for resource templates
-
Automatic conversion between sync/async resource specifications
-
Automatic resource specification through Spring beans:
@Bean
public List<McpStatelessServerFeatures.SyncResourceSpecification> myResources(...) {
var systemInfoResource = McpSchema.Resource.builder(...).build();
var resourceSpecification = new McpStatelessServerFeatures.SyncResourceSpecification(systemInfoResource, (context, request) -> {
try {
var systemInfo = Map.of(...);
String jsonContent = new JsonMapper().writeValueAsString(systemInfo);
return McpSchema.ReadResourceResult.builder(
List.of(McpSchema.TextResourceContents.builder(request.uri(), jsonContent).mimeType("application/json").build())).build();
}
catch (Exception e) {
throw new RuntimeException("Failed to generate system info", e);
}
});
return List.of(resourceSpecification);
}
Prompts
Provides a standardized way for servers to expose prompt templates to clients.
-
Template versioning
-
Automatic conversion between sync/async prompt specifications
-
Automatic prompt specification through Spring beans:
@Bean
public List<McpStatelessServerFeatures.SyncPromptSpecification> myPrompts() {
var prompt = McpSchema.Prompt.builder("greeting").description("A friendly greeting prompt")
.arguments(List.of(McpSchema.PromptArgument.builder("name").description("The name to greet").required(true).build())).build();
var promptSpecification = new McpStatelessServerFeatures.SyncPromptSpecification(prompt, (context, getPromptRequest) -> {
String nameArgument = (String) getPromptRequest.arguments().get("name");
if (nameArgument == null) { nameArgument = "friend"; }
var userMessage = PromptMessage.builder(Role.USER, TextContent.builder("Hello " + nameArgument + "! How can I assist you today?").build()).build();
return GetPromptResult.builder(List.of(userMessage)).description("A personalized greeting message").build();
});
return List.of(promptSpecification);
}
Completion
Provides a standardized way for servers to expose completion capabilities to clients.
-
Support for both sync and async completion specifications
-
Automatic registration through Spring beans:
@Bean
public List<McpStatelessServerFeatures.SyncCompletionSpecification> myCompletions() {
var completion = new McpStatelessServerFeatures.SyncCompletionSpecification(
McpSchema.PromptReference.builder("code-completion").title("Provides code completion suggestions").build(),
(exchange, request) -> {
// Implementation that returns completion suggestions
return new McpSchema.CompleteResult(
new McpSchema.CompleteResult.CompleteCompletion(List.of("python", "pytorch", "pyside"), 10, true));
}
);
return List.of(completion);
}
Usage Examples
Stateless Server Configuration
spring:
ai:
mcp:
server:
protocol: STATELESS
name: stateless-mcp-server
version: 1.0.0
type: ASYNC
instructions: "This stateless server is optimized for cloud deployments"
streamable-http:
mcp-endpoint: /api/mcp
Creating a Spring Boot Application with MCP Server
@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();
}
}
The auto-configuration will automatically register the tool callbacks as MCP tools. You can have multiple beans producing ToolCallbacks, and the auto-configuration will merge them.