MCP Server Boot Starter

Model Context Protocol (MCP) Servers are programs that expose specific capabilities to AI applications through standardized protocol interfaces. Each server provides focused functionality for a particular domain.spring-doc.cn

The Spring AI MCP Server Boot Starters provide auto-configuration for setting up MCP Servers in Spring Boot applications. They enable seamless integration of MCP server capabilities with Spring Boot’s auto-configuration system.spring-doc.cn

The MCP Server Boot Starters offer:spring-doc.cn

MCP Server Boot Starters

MCP Servers support multiple protocol and transport mechanisms. Use the dedicated starter and the correct spring.ai.mcp.server.protocol property to configure your server:spring-doc.cn

STDIO

Server Type Dependency Property

Standard Input/Output (STDIO)spring-doc.cn

spring-ai-starter-mcp-serverspring-doc.cn

spring.ai.mcp.server.stdio=truespring-doc.cn

WebMVC

Server Typespring-doc.cn

Dependencyspring-doc.cn

Propertyspring-doc.cn

SSE WebMVCspring-doc.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cn

spring.ai.mcp.server.protocol=SSE or emptyspring-doc.cn

Streamable-HTTP WebMVCspring-doc.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cn

spring.ai.mcp.server.protocol=STREAMABLEspring-doc.cn

Stateless WebMVCspring-doc.cn

spring-ai-starter-mcp-server-webmvcspring-doc.cn

spring.ai.mcp.server.protocol=STATELESSspring-doc.cn

WebMVC (Reactive)

Server Typespring-doc.cn

Dependencyspring-doc.cn

Propertyspring-doc.cn

SSE WebFluxspring-doc.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cn

spring.ai.mcp.server.protocol=SSE or emptyspring-doc.cn

Streamable-HTTP WebFluxspring-doc.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cn

spring.ai.mcp.server.protocol=STREAMABLEspring-doc.cn

Stateless WebFluxspring-doc.cn

spring-ai-starter-mcp-server-webfluxspring-doc.cn

spring.ai.mcp.server.protocol=STATELESSspring-doc.cn

Server Capabilities

Depending on the server and transport types, MCP Servers can support various capabilities, such as:spring-doc.cn

  • Tools - Allows servers to expose tools that can be invoked by language modelsspring-doc.cn

  • Resources - Provides a standardized way for servers to expose resources to clientsspring-doc.cn

  • Prompts - Provides a standardized way for servers to expose prompt templates to clientsspring-doc.cn

  • Utility/Completions - Provides a standardized way for servers to offer argument autocompletion suggestions for prompts and resource URIsspring-doc.cn

  • Utility/Logging - Provides a standardized way for servers to send structured log messages to clientsspring-doc.cn

  • Utility/Progress - Optional progress tracking for long-running operations through notification messagesspring-doc.cn

  • Utility/Ping - Optional health check mechanism for the server to report its statusspring-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

Server Protocols

MCP provides several protocol types including:spring-doc.cn

  • STDIO - In process (e.g. server runs inside the host application) protocol. Communication is over standard in and standard out. To enable the STDIO set spring.ai.mcp.server.stdio=true.spring-doc.cn

  • SSE - Server-sent events protocol for real-time updates. The server operates as an independent process that can handle multiple client connections.spring-doc.cn

  • Streamable-HTTP - 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. To enable the STREAMABLE protocol, set spring.ai.mcp.server.protocol=STREAMABLE.spring-doc.cn

  • Stateless - Stateless MCP servers are designed for simplified deployments where session state is not maintained between requests. They are ideal for microservices architectures and cloud-native deployments. To enable the STATELESS protocol, set spring.ai.mcp.server.protocol=STATELESS.spring-doc.cn

Sync/Async Server API Options

The MCP Server API supports imperative (i.e. synchronous) and reactive (e.g. asynchronous) programming models.spring-doc.cn

  • 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, set spring.ai.mcp.server.type=SYNC in your configuration. When activated, it automatically handles the configuration of synchronous tool specifications.spring-doc.cn

NOTE: The SYNC server will register only synchronous MCP annotated methods. Asynchronous methods will be ignored.spring-doc.cn

  • Asynchronous Server - The asynchronous server implementation uses McpAsyncServer and is optimized for non-blocking operations. To enable this server type, configure your application with spring.ai.mcp.server.type=ASYNC. This server type automatically sets up asynchronous tool specifications with built-in Project Reactor support.spring-doc.cn

NOTE: The ASYNC server will register only asynchronous MCP annotated methods. Synchronous methods will be ignored.spring-doc.cn

MCP Server Annotations

The MCP Server Boot Starters provide comprehensive support for annotation-based server development, allowing you to create MCP servers using declarative Java annotations instead of manual configuration.spring-doc.cn

Key Annotations

Special Parameters

The annotation system supports special parameter types that provide additional context:spring-doc.cn

  • McpMeta - Access metadata from MCP requestsspring-doc.cn

  • @McpProgressToken - Receive progress tokens for long-running operationsspring-doc.cn

  • McpSyncServerExchange/McpAsyncServerExchange - Full server context for advanced operationsspring-doc.cn

  • McpTransportContext - Lightweight context for stateless operationsspring-doc.cn

  • CallToolRequest - Dynamic schema support for flexible toolsspring-doc.cn

Simple Example

@Component
public class CalculatorTools {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }

    @McpResource(uri = "config://{key}", name = "Configuration")
    public String getConfig(String key) {
        return configData.get(key);
    }
}

Auto-Configuration

With Spring Boot auto-configuration, annotated beans are automatically detected and registered:spring-doc.cn

@SpringBootApplication
public class McpServerApplication {
    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }
}

The auto-configuration will:spring-doc.cn

  1. Scan for beans with MCP annotationsspring-doc.cn

  2. Create appropriate specificationsspring-doc.cn

  3. Register them with the MCP serverspring-doc.cn

  4. Handle both sync and async implementations based on configurationspring-doc.cn

Configuration Properties

Configure the server annotation scanner:spring-doc.cn

spring:
  ai:
    mcp:
      server:
        type: SYNC  # or ASYNC
        annotation-scanner:
          enabled: true

Additional Resources

Example Applications

Additional Resources