This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.0.1!spring-doc.cn

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.spring-doc.cn

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.spring-doc.cn

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:spring-doc.cn

<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.spring-doc.cn

  • Full MCP server capabilities with Spring MVC Streamable transportspring-doc.cn

  • Suppport for tools, resources, prompts, completion, logging, progression, ping, root-changes capabilitiesspring-doc.cn

  • Persistent connection managementspring-doc.cn

Streamable-HTTP WebFlux Server

Use the spring-ai-starter-mcp-server-webflux dependency:spring-doc.cn

<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.spring-doc.cn

  • Reactive MCP server with WebFlux Streamable transportspring-doc.cn

  • Suppport for tools, resources, prompts, completion, logging, progression, ping, root-changes capabilitiesspring-doc.cn

  • Non-blocking, persistent connection managementspring-doc.cn

Configuration Properties

Common Properties

All common properties are prefixed with spring.ai.mcp.server:spring-doc.cn

Property Description Default

enabledspring-doc.cn

Enable/disable the streamable MCP serverspring-doc.cn

truespring-doc.cn

protocolspring-doc.cn

MCP server protocolspring-doc.cn

Must be set to STREAMABLE to enable the streamable serverspring-doc.cn

tool-callback-converterspring-doc.cn

Enable/disable the conversion of Spring AI ToolCallbacks into MCP Tool specsspring-doc.cn

truespring-doc.cn

namespring-doc.cn

Server name for identificationspring-doc.cn

mcp-serverspring-doc.cn

versionspring-doc.cn

Server versionspring-doc.cn

1.0.0spring-doc.cn

instructionsspring-doc.cn

Optional instructions for client interactionspring-doc.cn

nullspring-doc.cn

typespring-doc.cn

Server type (SYNC/ASYNC)spring-doc.cn

SYNCspring-doc.cn

capabilities.resourcespring-doc.cn

Enable/disable resource capabilitiesspring-doc.cn

truespring-doc.cn

capabilities.toolspring-doc.cn

Enable/disable tool capabilitiesspring-doc.cn

truespring-doc.cn

capabilities.promptspring-doc.cn

Enable/disable prompt capabilitiesspring-doc.cn

truespring-doc.cn

capabilities.completionspring-doc.cn

Enable/disable completion capabilitiesspring-doc.cn

truespring-doc.cn

resource-change-notificationspring-doc.cn

Enable resource change notificationsspring-doc.cn

truespring-doc.cn

prompt-change-notificationspring-doc.cn

Enable prompt change notificationsspring-doc.cn

truespring-doc.cn

tool-change-notificationspring-doc.cn

Enable tool change notificationsspring-doc.cn

truespring-doc.cn

tool-response-mime-typespring-doc.cn

Response MIME type per tool namespring-doc.cn

-spring-doc.cn

request-timeoutspring-doc.cn

Request timeout durationspring-doc.cn

20 secondsspring-doc.cn

Streamable-HTTP Properties

All streamable-HTTP properties are prefixed with spring.ai.mcp.server.streamable-http:spring-doc.cn

Property Description Default

mcp-endpointspring-doc.cn

Custom MCP endpoint pathspring-doc.cn

/mcpspring-doc.cn

keep-alive-intervalspring-doc.cn

Connection keep-alive intervalspring-doc.cn

null (disabled)spring-doc.cn

disallow-deletespring-doc.cn

Disallow delete operationsspring-doc.cn

falsespring-doc.cn

Features and Capabilities

The MCP Server supports four main capability types that can be individually enabled or disabled:spring-doc.cn

  • Tools - Enable/disable tool capabilities with spring.ai.mcp.server.capabilities.tool=true|falsespring-doc.cn

  • Resources - Enable/disable resource capabilities with spring.ai.mcp.server.capabilities.resource=true|falsespring-doc.cn

  • Prompts - Enable/disable prompt capabilities with spring.ai.mcp.server.capabilities.prompt=true|falsespring-doc.cn

  • Completions - Enable/disable completion capabilities with spring.ai.mcp.server.capabilities.completion=true|falsespring-doc.cn

All capabilities are enabled by default. Disabling a capability will prevent the server from registering and exposing the corresponding features to clients.spring-doc.cn

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:spring-doc.cn

Tools

Allows servers to expose tools that can be invoked by language models. The MCP Server Boot Starter provides:spring-doc.cn

@Bean
public ToolCallbackProvider myTools(...) {
    List<ToolCallback> tools = ...
    return ToolCallbackProvider.from(tools);
}

or using the low-level API:spring-doc.cn

@Bean
public List<McpServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpServerFeatures.SyncToolSpecification> tools = ...
    return tools;
}

The auto-configuration will automatically detect and register all tool callbacks from:spring-doc.cn

Tools are de-duplicated by name, with the first occurrence of each tool name being used.spring-doc.cn

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(…​).spring-doc.cn

Resources

Provides a standardized way for servers to expose resources to clients.spring-doc.cn

@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.spring-doc.cn

@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.spring-doc.cn

  • Support for both sync and async completion specificationsspring-doc.cn

  • Automatic registration through Spring beans:spring-doc.cn

@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:spring-doc.cn

(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:spring-doc.cn

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:spring-doc.cn

(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.spring-doc.cn

mcpClientSpec.progressConsumer((McpSchema.ProgressNotification progress) -> {
    // Handle progress notifications
});

Root List Changes

When roots change, clients that support listChanged send a root change notification.spring-doc.cn

@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:spring-doc.cn

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

Keep Alive

Server can optionally, periodically issue pings to connected clients to verify connection health.spring-doc.cn

By default, keep-alive is disabled. To enable keep-alive, set the keep-alive-interval property in your configuration:spring-doc.cn

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.spring-doc.cn