This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.0.1! |
Streamable-HTTP MCP Servers
The Streamable HTTP transport allows MCP servers to operate as independent processes that can handle multiple client connections using HTTP POST and GET requests, with optional Server-Sent Events (SSE) streaming for multiple server messages. It replaces the SSE transport.
These servers, introduced with spec version 2025-03-26, are ideal for applications that need to notify clients about dynamic changes to tools, resources, or prompts.
Set the spring.ai.mcp.server.protocol=STREAMABLE property
|
Use the Streamable-HTTP clients to connect to the Streamable-HTTP servers. |
Streamable-HTTP 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 STREAMABLE
.
-
Full MCP server capabilities with Spring MVC Streamable transport
-
Suppport for tools, resources, prompts, completion, logging, progression, ping, root-changes capabilities
-
Persistent connection management
Streamable-HTTP 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 STREAMABLE
.
-
Reactive MCP server with WebFlux Streamable transport
-
Suppport for tools, resources, prompts, completion, logging, progression, ping, root-changes capabilities
-
Non-blocking, persistent connection management
Configuration Properties
Common Properties
All common properties are prefixed with spring.ai.mcp.server
:
Property | Description | Default |
---|---|---|
|
Enable/disable the streamable 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 |
|
|
Enable resource change notifications |
|
|
Enable prompt change notifications |
|
|
Enable tool change notifications |
|
|
Response MIME type per tool name |
|
|
Request timeout duration |
|
Streamable-HTTP Properties
All streamable-HTTP properties are prefixed with spring.ai.mcp.server.streamable-http
:
Property | Description | Default |
---|---|---|
|
Custom MCP endpoint path |
|
|
Connection keep-alive interval |
|
|
Disallow delete operations |
|
Features and Capabilities
The MCP Server supports four main capability types that can be individually enabled or disabled:
-
Tools - Enable/disable tool capabilities with
spring.ai.mcp.server.capabilities.tool=true|false
-
Resources - Enable/disable resource capabilities with
spring.ai.mcp.server.capabilities.resource=true|false
-
Prompts - Enable/disable prompt capabilities with
spring.ai.mcp.server.capabilities.prompt=true|false
-
Completions - Enable/disable completion capabilities with
spring.ai.mcp.server.capabilities.completion=true|false
All capabilities are enabled by default. Disabling a capability will prevent the server from registering and exposing the corresponding features to clients.
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:
Tools
Allows servers to expose tools that can be invoked by language models. The MCP Server Boot Starter provides:
-
Change notification support
-
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<McpServerFeatures.SyncToolSpecification> myTools(...) {
List<McpServerFeatures.SyncToolSpecification> tools = ...
return tools;
}
The auto-configuration will automatically detect and register all tool callbacks from:
-
Individual
ToolCallback
beans -
Lists of
ToolCallback
beans -
ToolCallbackProvider
beans
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
The ToolContext is supported, allowing contextual information to be passed to tool calls. It contains an McpSyncServerExchange
instance under the exchange
key, accessible via McpToolUtils.getMcpExchange(toolContext)
. See this example demonstrating exchange.loggingNotification(…)
and exchange.createMessage(…)
.
Resources
Provides a standardized way for servers to expose resources to clients.
-
Static and dynamic resource specifications
-
Optional change notifications
-
Support for resource templates
-
Automatic conversion between sync/async resource specifications
-
Automatic resource specification through Spring beans:
@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);
}
Prompts
Provides a standardized way for servers to expose prompt templates to clients.
-
Change notification support
-
Template versioning
-
Automatic conversion between sync/async prompt specifications
-
Automatic prompt specification through 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);
}
Completions
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<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
Provides a standardized way for servers to send structured log messages to clients.
From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange
/McpAsyncServerExchange
exchange
object to send logging messages:
(exchange, request) -> {
exchange.loggingNotification(LoggingMessageNotification.builder()
.level(LoggingLevel.INFO)
.logger("test-logger")
.data("This is a test log message")
.build());
}
On the MCP client you can register logging consumers to handle these messages:
mcpClientSpec.loggingConsumer((McpSchema.LoggingMessageNotification log) -> {
// Handle log messages
});
Progress
Provides a standardized way for servers to send progress updates to clients.
From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange
/McpAsyncServerExchange
exchange
object to send progress notifications:
(exchange, request) -> {
exchange.progressNotification(ProgressNotification.builder()
.progressToken("test-progress-token")
.progress(0.25)
.total(1.0)
.message("tool call in progress")
.build());
}
The Mcp Client can receive progress notifications and update its UI accordingly. For this it needs to register a progress consumer.
mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
// Handle progress notifications
});
Root List Changes
When roots change, clients that support listChanged
send a root change notification.
-
Support for monitoring root changes
-
Automatic conversion to async consumers for reactive applications
-
Optional registration through Spring beans
@Bean
public BiConsumer<McpSyncServerExchange, List<McpSchema.Root>> rootsChangeHandler() {
return (exchange, roots) -> {
logger.info("Registering root resources: {}", roots);
};
}
Ping
Ping mechanism for the server to verify that its clients are still alive.
From within the tool, resource, prompt or completion call handler use the provided McpSyncServerExchange
/McpAsyncServerExchange
exchange
object to send ping messages:
(exchange, request) -> {
exchange.ping();
}
Keep Alive
Server can optionally, periodically issue pings to connected clients to verify connection health.
By default, keep-alive is disabled.
To enable keep-alive, set the keep-alive-interval
property in your configuration:
spring:
ai:
mcp:
server:
streamable-http:
keep-alive-interval: 30s
Currently, for streamable-http servers, the keep-alive mechanism is available only for the Listening for Messages from the Server (SSE) connection. |
Usage Examples
Streamable HTTP Server Configuration
# Using spring-ai-starter-mcp-server-streamable-webmvc
spring:
ai:
mcp:
server:
protocol: STREAMABLE
name: streamable-mcp-server
version: 1.0.0
type: SYNC
instructions: "This streamable server provides real-time notifications"
resource-change-notification: true
tool-change-notification: true
prompt-change-notification: true
streamable-http:
mcp-endpoint: /api/mcp
keep-alive-interval: 30s
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.