STDIO and SSE MCP Servers

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

The STDIO and SSE MCP Servers support multiple transport mechanisms, each with its dedicated starter.spring-doc.cn

Use the STDIO clients or SSE clients to connect to the STDIO and SSE servers.

STDIO MCP Server

Full MCP Server feature support with STDIO server transport.spring-doc.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

Suitable for command-line and desktop toolsspring-doc.cn
No additional web dependencies requiredspring-doc.cn
Configuration of basic server componentsspring-doc.cn
Handling of tool, resource, and prompt specificationsspring-doc.cn
Management of server capabilities and change notificationsspring-doc.cn
Support for both sync and async server implementationsspring-doc.cn

SSE WebMVC Server

Full MCP Server feature support with SSE (Server-Sent Events) server transport based on Spring MVC and an optional STDIO transport.spring-doc.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

HTTP-based transport using Spring MVC (WebMvcSseServerTransportProvider)spring-doc.cn
Automatically configured SSE endpointsspring-doc.cn
Optional STDIO transport (enabled by setting spring.ai.mcp.server.stdio=true)spring-doc.cn
Includes spring-boot-starter-web and mcp-spring-webmvc dependenciesspring-doc.cn

SSE WebFlux Server

Full MCP Server feature support with SSE (Server-Sent Events) server transport based on Spring WebFlux and an optional STDIO transport.spring-doc.cn

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

The starter activates the McpWebFluxServerAutoConfiguration and McpServerAutoConfiguration auto-configurations to provide:spring-doc.cn

Reactive transport using Spring WebFlux (WebFluxSseServerTransportProvider)spring-doc.cn
Automatically configured reactive SSE endpointsspring-doc.cn
Optional STDIO transport (enabled by setting spring.ai.mcp.server.stdio=true)spring-doc.cn
Includes spring-boot-starter-webflux and mcp-spring-webflux dependenciesspring-doc.cn

Due to Spring Boot’s default behavior, when both org.springframework.web.servlet.DispatcherServlet and org.springframework.web.reactive.DispatcherHandler are present on the classpath, Spring Boot will prioritize DispatcherServlet. As a result, if your project uses spring-boot-starter-web, it is recommended to use spring-ai-starter-mcp-server-webmvc instead of spring-ai-starter-mcp-server-webflux.spring-doc.cn

Configuration Properties

Common Properties

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

Property Description Default

Property	Description	Default
`enabled`spring-doc.cn	Enable/disable the MCP serverspring-doc.cn	`true`spring-doc.cn
`tool-callback-converter`spring-doc.cn	Enable/disable the conversion of Spring AI ToolCallbacks into MCP Tool specsspring-doc.cn	`true`spring-doc.cn
`stdio`spring-doc.cn	Enable/disable STDIO transportspring-doc.cn	`false`spring-doc.cn
`name`spring-doc.cn	Server name for identificationspring-doc.cn	`mcp-server`spring-doc.cn
`version`spring-doc.cn	Server versionspring-doc.cn	`1.0.0`spring-doc.cn
`instructions`spring-doc.cn	Optional instructions to provide guidance to the client on how to interact with this serverspring-doc.cn	`null`spring-doc.cn
`type`spring-doc.cn	Server type (SYNC/ASYNC)spring-doc.cn	`SYNC`spring-doc.cn
`capabilities.resource`spring-doc.cn	Enable/disable resource capabilitiesspring-doc.cn	`true`spring-doc.cn
`capabilities.tool`spring-doc.cn	Enable/disable tool capabilitiesspring-doc.cn	`true`spring-doc.cn
`capabilities.prompt`spring-doc.cn	Enable/disable prompt capabilitiesspring-doc.cn	`true`spring-doc.cn
`capabilities.completion`spring-doc.cn	Enable/disable completion capabilitiesspring-doc.cn	`true`spring-doc.cn
`resource-change-notification`spring-doc.cn	Enable resource change notificationsspring-doc.cn	`true`spring-doc.cn
`prompt-change-notification`spring-doc.cn	Enable prompt change notificationsspring-doc.cn	`true`spring-doc.cn
`tool-change-notification`spring-doc.cn	Enable tool change notificationsspring-doc.cn	`true`spring-doc.cn
`tool-response-mime-type`spring-doc.cn	Optional response MIME type per tool name. For example, `spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png` will associate the `image/png` MIME type with the `generateImage()` tool namespring-doc.cn	`-`spring-doc.cn
`request-timeout`spring-doc.cn	Duration to wait for server responses before timing out requests. Applies to all requests made through the client, including tool calls, resource access, and prompt operationsspring-doc.cn	`20 seconds`spring-doc.cn

enabledspring-doc.cn

Enable/disable the MCP serverspring-doc.cn

truespring-doc.cn

tool-callback-converterspring-doc.cn

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

truespring-doc.cn

stdiospring-doc.cn

Enable/disable STDIO transportspring-doc.cn

falsespring-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 to provide guidance to the client on how to interact with this serverspring-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

Optional response MIME type per tool name. For example, spring.ai.mcp.server.tool-response-mime-type.generateImage=image/png will associate the image/png MIME type with the generateImage() tool namespring-doc.cn

-spring-doc.cn

request-timeoutspring-doc.cn

Duration to wait for server responses before timing out requests. Applies to all requests made through the client, including tool calls, resource access, and prompt operationsspring-doc.cn

20 secondsspring-doc.cn

SSE Properties

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

Property Description Default

Property	Description	Default
`sse-message-endpoint`spring-doc.cn	Custom SSE message endpoint path for web transport to be used by the client to send messagesspring-doc.cn	`/mcp/message`spring-doc.cn
`sse-endpoint`spring-doc.cn	Custom SSE endpoint path for web transportspring-doc.cn	`/sse`spring-doc.cn
`base-url`spring-doc.cn	Optional URL prefix. For example, `base-url=/api/v1` means that the client should access the SSE endpoint at `/api/v1` + `sse-endpoint` and the message endpoint is `/api/v1` + `sse-message-endpoint`spring-doc.cn	`-`spring-doc.cn
`keep-alive-interval`spring-doc.cn	Connection keep-alive intervalspring-doc.cn	`null` (disabled)spring-doc.cn

sse-message-endpointspring-doc.cn

Custom SSE message endpoint path for web transport to be used by the client to send messagesspring-doc.cn

/mcp/messagespring-doc.cn

sse-endpointspring-doc.cn

Custom SSE endpoint path for web transportspring-doc.cn

/ssespring-doc.cn

base-urlspring-doc.cn

Optional URL prefix. For example, base-url=/api/v1 means that the client should access the SSE endpoint at /api/v1 + sse-endpoint and the message endpoint is /api/v1 + sse-message-endpointspring-doc.cn

-spring-doc.cn

keep-alive-intervalspring-doc.cn

Connection keep-alive intervalspring-doc.cn

null (disabled)spring-doc.cn

For backward compatibility reasons, the SSE properties do not have additional suffix (like .sse).

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: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

Change notification supportspring-doc.cn
Spring AI Tools are automatically converted to sync/async specifications based on the server typespring-doc.cn
Automatic tool specification through Spring beans: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

Individual ToolCallback beansspring-doc.cn
Lists of ToolCallback beansspring-doc.cn
ToolCallbackProvider beansspring-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

Static and dynamic resource specificationsspring-doc.cn
Optional change notificationsspring-doc.cn
Support for resource templatesspring-doc.cn
Automatic conversion between sync/async resource specificationsspring-doc.cn
Automatic resource specification through Spring beans: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

Change notification supportspring-doc.cn
Template versioningspring-doc.cn
Automatic conversion between sync/async prompt specificationsspring-doc.cn
Automatic prompt specification through Spring beans: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

Support for monitoring root changesspring-doc.cn
Automatic conversion to async consumers for reactive applicationsspring-doc.cn
Optional registration through Spring beansspring-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:
        keep-alive-interval: 30s

Usage Examples

Standard STDIO Server Configuration

# Using spring-ai-starter-mcp-server
spring:
  ai:
    mcp:
      server:
        name: stdio-mcp-server
        version: 1.0.0
        type: SYNC

WebMVC Server Configuration

# Using spring-ai-starter-mcp-server-webmvc
spring:
  ai:
    mcp:
      server:
        name: webmvc-mcp-server
        version: 1.0.0
        type: SYNC
        instructions: "This server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        keep-alive-interval: 30s

WebFlux Server Configuration

# Using spring-ai-starter-mcp-server-webflux
spring:
  ai:
    mcp:
      server:
        name: webflux-mcp-server
        version: 1.0.0
        type: ASYNC  # Recommended for reactive applications
        instructions: "This reactive server provides weather information tools and resources"
        capabilities:
          tool: true
          resource: true
          prompt: true
          completion: true
        # sse properties
        sse-message-endpoint: /mcp/messages
        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

Example Applications

Weather Server (WebFlux) - Spring AI MCP Server Boot Starter with WebFlux transportspring-doc.cn
Weather Server (STDIO) - Spring AI MCP Server Boot Starter with STDIO transportspring-doc.cn
Weather Server Manual Configuration - Spring AI MCP Server Boot Starter that doesn’t use auto-configuration but uses the Java SDK to configure the server manuallyspring-doc.cn