MCP Server Boot Starter
The Spring AI MCP (Model Context Protocol) Server Boot Starter provides auto-configuration for setting up an MCP server in Spring Boot applications. It enables seamless integration of MCP server capabilities with Spring Boot’s auto-configuration system.
The MCP Server Boot Starter offers:
-
Automatic configuration of MCP server components
-
Support for both synchronous and asynchronous operation modes
-
Multiple transport layer options
-
Flexible tool, resource, and prompt registration
-
Change notification capabilities
Starters
Choose one of the following starters based on your transport requirements:
Standard MCP Server
Full MCP Server features support with STDIO
server transport.
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>
-
Suitable for command-line and desktop tools
-
No additional web dependencies required
The starter activates the McpServerAutoConfiguration
auto-configuration responsible for:
-
Configuring the basic server components
-
Handling tool, resource, and prompt registrations
-
Managing server capabilities and change notifications
-
Providing both sync and async server implementations
WebMVC Server Transport
Full MCP Server features support with SSE
(Server-Sent Events) server transport based on Spring MVC and an optional STDIO
transport.
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-webmvc-spring-boot-starter</artifactId>
</dependency>
The starter activates the McpWebMvcServerAutoConfiguration
and McpServerAutoConfiguration
auto-configurations to provide:
-
HTTP-based transport using Spring MVC (
WebMvcSseServerTransport
) -
Automatically configured SSE endpoints
-
Optional
STDIO
transport (enabled by settingspring.ai.mcp.server.stdio=true
) -
Included
spring-boot-starter-web
andmcp-spring-webmvc
dependencies
WebFlux Server Transport
Full MCP Server features support with SSE
(Server-Sent Events) server transport based on Spring WebFlux and an optional STDIO
transport.
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-webflux-spring-boot-starter</artifactId>
</dependency>
The starter activates the McpWebFluxServerAutoConfiguration
and McpServerAutoConfiguration
auto-configurations to provide:
-
Reactive transport using Spring WebFlux (
WebFluxSseServerTransport
) -
Automatically configured reactive SSE endpoints
-
Optional
STDIO
transport (enabled by settingspring.ai.mcp.server.stdio=true
) -
Included
spring-boot-starter-webflux
andmcp-spring-webflux
dependencies
Configuration Properties
All properties are prefixed with spring.ai.mcp.server
:
Property | Description | Default |
---|---|---|
|
Enable/disable the MCP server |
|
|
Enable/disable stdio transport |
|
|
Server name for identification |
|
|
Server version |
|
|
Server type (SYNC/ASYNC) |
|
|
Enable resource change notifications |
|
|
Enable tool change notifications |
|
|
Enable prompt change notifications |
|
|
SSE endpoint path for web transport |
|
Sync/Async Server Types
-
Synchronous Server - The default server type implemented using
McpSyncServer
. It is designed for straightforward request-response patterns in your applications. To enable this server type, setspring.ai.mcp.server.type=SYNC
in your configuration. When activated, it automatically handles the configuration of synchronous tool registrations. -
Asynchronous Server - The asynchronous server implementation uses
McpAsyncServer
and is optimized for non-blocking operations. To enable this server type, configure your application withspring.ai.mcp.server.type=ASYNC
. This server type automatically sets up asynchronous tool registrations with built-in Project Reactor support.
Transport Options
The MCP Server supports three transport mechanisms, each with its dedicated starter:
-
Standard Input/Output (STDIO) -
spring-ai-mcp-server-spring-boot-starter
-
Spring MVC (Server-Sent Events) -
spring-ai-mcp-server-webmvc-spring-boot-starter
-
Spring WebFlux (Reactive SSE) -
spring-ai-mcp-server-webflux-spring-boot-starter
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 registrations based on server type:
Tools
Allows servers to expose tools that can be invoked by language models. The MCP Server Boot Starter provides:
-
Change notification support
-
Tools are automatically converted to sync/async registrations based on server type
-
Automatic tool registration through Spring beans:
@Bean
public ToolCallbackProvider myTools(...) {
List<ToolCallback> tools = ...
return ToolCallbackProvider.from(tools);
}
or using the low-level API:
@Bean
public List<McpServerFeatures.SyncToolRegistration> myTools(...) {
List<McpServerFeatures.SyncToolRegistration> tools = ...
return tools;
}
Resource Management
Provides a standardized way for servers to expose resources to clients.
-
Static and dynamic resource registration
-
Optional change notifications
-
Support for resource templates
-
Automatic conversion between sync/async resource registrations
-
Automatic resource registration through Spring beans:
@Bean
public List<McpServerFeatures.SyncResourceRegistration> myResources(...) {
var systemInfoResource = new McpSchema.Resource(...);
var resourceRegistration = new McpServerFeatures.SyncResourceRegistration(systemInfoResource, 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(resourceRegistration);
}
Prompt Management
Provides a standardized way for servers to expose prompt templates to clients.
-
Change notification support
-
Template versioning
-
Automatic conversion between sync/async prompt registrations
-
Automatic prompt registration through Spring beans:
@Bean
public List<McpServerFeatures.SyncPromptRegistration> myPrompts() {
var prompt = new McpSchema.Prompt("greeting", "A friendly greeting prompt",
List.of(new McpSchema.PromptArgument("name", "The name to greet", true)));
var promptRegistration = new McpServerFeatures.SyncPromptRegistration(prompt, 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(promptRegistration);
}
Root Change Consumers
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 Consumer<List<McpSchema.Root>> rootsChangeConsumer() {
return roots -> {
logger.info("Registering root resources: {}", roots);
};
}
Usage Examples
Standard STDIO Server Configuration
# Using spring-ai-mcp-server-spring-boot-starter
spring:
ai:
mcp:
server:
name: stdio-mcp-server
version: 1.0.0
type: SYNC
WebMVC Server Configuration
# Using spring-ai-mcp-server-webmvc-spring-boot-starter
spring:
ai:
mcp:
server:
name: webmvc-mcp-server
version: 1.0.0
type: SYNC
sse-message-endpoint: /mcp/messages
WebFlux Server Configuration
# Using spring-ai-mcp-server-webflux-spring-boot-starter
spring:
ai:
mcp:
server:
name: webflux-mcp-server
version: 1.0.0
type: ASYNC # Recommended for reactive applications
sse-message-endpoint: /mcp/messages
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. The auto-configuration will merge them.
Example Applications
-
Weather Server (WebFlux) - Spring AI MCP Server Boot Starter with WebFlux transport.
-
Weather Server (STDIO) - Spring AI MCP Server Boot Starter with STDIO transport.
-
Book Library Server (WebFlux) - Spring AI MCP Server Boot Starter with WebFlux transport.
-
Weather Server Manual Configuration - Spring AI MCP Server Boot Starter that doesn’t use auto-configuration but the Java SDK to configure the server manually.