This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.0.3!

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

enabled

Enable/disable the stateless MCP server

true

protocol

MCP server protocol

Must be set to STATELESS to enable the stateless server

tool-callback-converter

Enable/disable the conversion of Spring AI ToolCallbacks into MCP Tool specs

true

name

Server name for identification

mcp-server

version

Server version

1.0.0

instructions

Optional instructions for client interaction

null

type

Server type (SYNC/ASYNC)

SYNC

capabilities.resource

Enable/disable resource capabilities

true

capabilities.tool

Enable/disable tool capabilities

true

capabilities.prompt

Enable/disable prompt capabilities

true

capabilities.completion

Enable/disable completion capabilities

true

tool-response-mime-type

Response MIME type per tool name

-

request-timeout

Request timeout duration

20 seconds

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

enabled

Enable/disable the MCP server annotations auto-scanning

true

Stateless Connection Properties

All connection properties are prefixed with spring.ai.mcp.server.stateless:

Property Description Default

mcp-endpoint

Custom MCP endpoint path

/mcp

disallow-delete

Disallow delete operations

false

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:

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<McpStatelessServerFeatures.SyncToolSpecification> myTools(...) {
    List<McpStatelessServerFeatures.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 is not applicable for stateless servers.

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<McpStatelessServerFeatures.SyncResourceSpecification> myResources(...) {
    var systemInfoResource = new McpSchema.Resource(...);
    var resourceSpecification = new McpStatelessServerFeatures.SyncResourceSpecification(systemInfoResource, (context, 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<McpStatelessServerFeatures.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 McpStatelessServerFeatures.SyncPromptSpecification(prompt, (context, 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);
}

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(
        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);
}

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.