Architecture

The Spring AI MCP Server Starter provides a comprehensive framework for building Model Context Protocol servers with Spring Boot. Understanding its architecture helps developers leverage the framework effectively.

Core Components

Auto-configuration Layer

The starter provides extensive auto-configuration that automatically sets up MCP server components based on classpath and configuration:

• McpServerAutoConfiguration - Main server configuration and lifecycle management
• McpServerObjectMapperAutoConfiguration - Jackson ObjectMapper customization for MCP schema serialization
• McpServerAnnotationScannerAutoConfiguration - Scans for and processes MCP annotations (@McpTool, @McpResource, etc.)
• McpServerSpecificationFactoryAutoConfiguration - Creates MCP specifications from various sources
• ToolCallbackConverterAutoConfiguration - Converts Spring AI ToolCallbacks to MCP tool specifications

Transport Layer

Multiple transport mechanisms are supported with dedicated auto-configurations:

STDIO Transport

• Command-line interface transport using standard input/output
• No web server required
• Ideal for CLI tools and local development
• Configuration: spring.ai.mcp.server.stdio=true

SSE (Server-Sent Events) Transport

• HTTP-based bidirectional communication
• SSE for server-to-client streaming
• HTTP POST for client-to-server messages
• Implementations: McpServerSseWebFluxAutoConfiguration, McpServerSseWebMvcAutoConfiguration
• Supports both reactive (WebFlux) and servlet (WebMVC) stacks

Streamable HTTP Transport

• HTTP streaming protocol for bidirectional communication
• Single endpoint for both directions
• Implementations: McpServerStreamableHttpWebFluxAutoConfiguration, McpServerStreamableHttpWebMvcAutoConfiguration
• Supports stateful and stateless modes

Stateless Transport

• Stateless HTTP protocol for horizontally scalable deployments
• No bidirectional operations (logging, progress, elicitation, sampling)
• Configuration: McpServerStatelessAutoConfiguration

Specification System

The framework uses a specification-based architecture where capabilities are defined as specifications before registration:

Server-side Specifications (for exposing functionality):

• SyncToolSpecification / AsyncToolSpecification - Tool implementations
• SyncResourceSpecification / AsyncResourceSpecification - Resource providers
• SyncResourceTemplateSpecification / AsyncResourceTemplateSpecification - Resource templates with URI placeholders
• SyncPromptSpecification / AsyncPromptSpecification - Prompt generators
• SyncCompletionSpecification / AsyncCompletionSpecification - Auto-completion providers

Stateless Variants:

• StatelessSyncToolSpecification / StatelessAsyncToolSpecification
• StatelessSyncResourceSpecification / StatelessAsyncResourceSpecification
• StatelessSyncPromptSpecification / StatelessAsyncPromptSpecification

Annotation Processing

The annotation scanner discovers and converts annotated methods to specifications:

Process Flow:

1. Discovery - ApplicationContext scanned for Spring beans
2. Method Analysis - Bean methods inspected for MCP annotations
3. Schema Generation - JSON schemas automatically generated from method signatures
4. Specification Creation - Annotations converted to appropriate specification types
5. Filtering - Specifications filtered based on server type (sync/async) and protocol (stateful/stateless)
6. Registration - Valid specifications registered with the MCP server

Providers:

• SyncMcpAnnotationProviders - Creates sync specifications from annotations
• AsyncMcpAnnotationProviders - Creates async specifications from annotations

Context System

Request contexts provide access to MCP features during execution:

Context Hierarchy:

McpTransportContext (lightweight, stateless-compatible)
    ├── McpSyncRequestContext (full sync context)
    └── McpAsyncRequestContext (full async context)

Context Features:

• Transport Context - Basic transport metadata (request ID, transport info)
• Request Context - Full request access, logging, progress, elicitation, sampling
• Exchange Objects - Low-level MCP protocol access (McpSyncServerExchange, McpAsyncServerExchange)

Tool Integration Layer

Bridges Spring AI's ToolCallback interface with MCP:

Client-side (consuming remote MCP servers):

• SyncMcpToolCallback / AsyncMcpToolCallback - Wrap remote MCP tools as Spring AI ToolCallbacks
• SyncMcpToolCallbackProvider / AsyncMcpToolCallbackProvider - Discover and provide tools from multiple servers

Server-side (exposing tools via MCP):

• Automatic conversion of Spring AI ToolCallback beans to MCP tool specifications
• Configurable via spring.ai.mcp.server.tool-callback-converter

Customization Points

Client Customizers:

• McpSyncClientCustomizer - Customize synchronous client connections
• McpAsyncClientCustomizer - Customize asynchronous client connections

Strategy Interfaces:

• McpToolFilter - Filter discovered tools
• McpToolNamePrefixGenerator - Generate unique tool names
• ToolContextToMcpMetaConverter - Convert Spring AI context to MCP metadata

Utilities:

• McpToolUtils - Helper methods for tool operations
• SyncMcpAnnotationProviders / AsyncMcpAnnotationProviders - Manual annotation processing
• DefaultMcpToolNamePrefixGenerator - Default naming strategy with conflict resolution

API Type Support

Synchronous (SYNC) Servers

• Execution Model - Blocking operations on traditional servlet threads
• Return Types - Primitives, objects, collections, MCP result types
• Use Cases - Simple operations, traditional Spring MVC applications, JDBC database access
• Configuration - spring.ai.mcp.server.type=SYNC (default)

Asynchronous (ASYNC) Servers

• Execution Model - Non-blocking reactive operations using Project Reactor
• Return Types - Mono<T>, Flux<T>, or any synchronous type (auto-wrapped)
• Use Cases - High concurrency, non-blocking I/O, reactive database access (R2DBC)
• Configuration - spring.ai.mcp.server.type=ASYNC

Protocol Support

Stateful Protocols (SSE, STREAMABLE)

Capabilities:

• Bidirectional communication
• Server-to-client notifications (logging, progress)
• Client-to-server requests (elicitation, sampling)
• Connection state management
• Roots management

Context Types:

• McpSyncRequestContext / McpAsyncRequestContext

Stateless Protocol

Capabilities:

• Request/response only
• No bidirectional operations
• Horizontally scalable
• Load balancer friendly

Context Types:

• McpTransportContext only

Limitations:

• No logging notifications
• No progress tracking
• No elicitation
• No sampling
• Methods requiring full request context are filtered out

Change Notification System

The framework supports dynamic capability changes:

Server-to-Client Notifications:

• Tool list changes (spring.ai.mcp.server.tool-change-notification)
• Resource list changes (spring.ai.mcp.server.resource-change-notification)
• Prompt list changes (spring.ai.mcp.server.prompt-change-notification)

Event System:

• McpToolsChangedEvent - Published when tools change on a connection
• Spring's ApplicationListener integration for automatic cache invalidation
• ToolCallbackProvider implementations automatically respond to events

Capability Configuration

Capabilities can be selectively enabled/disabled:

spring.ai.mcp.server.capabilities.tool=true         # Tool calling
spring.ai.mcp.server.capabilities.resource=true     # Resource access
spring.ai.mcp.server.capabilities.prompt=true       # Prompt templates
spring.ai.mcp.server.capabilities.completion=true   # Auto-completion

This allows servers to expose only required capabilities, reducing attack surface and simplifying deployment.

Spring Boot Integration

Dependency Injection

All components are Spring-managed beans:

• Annotated tool classes are regular @Component beans
• Full Spring DI support (constructor injection, @Autowired, etc.)
• Access to other Spring beans (services, repositories, etc.)
• Transaction management support
• AOP integration (security, logging, etc.)

Configuration Properties

Externalized configuration using Spring Boot's property system:

• Properties files (application.properties, application.yml)
• Environment variables
• Command-line arguments
• Spring profiles for environment-specific configuration
• @ConfigurationProperties binding with validation

Auto-configuration

Conditional auto-configuration based on:

• Classpath presence (WebFlux vs WebMVC)
• Property values (spring.ai.mcp.server.enabled)
• Bean presence/absence
• Custom conditions

Execution Flow

Server-side Tool Execution

1. Client Request - MCP client sends tool call request
2. Transport Layer - Request received via STDIO/SSE/HTTP
3. Deserialization - JSON parsed to CallToolRequest
4. Tool Resolution - Tool name matched to registered specification
5. Context Creation - Appropriate context object created (McpSyncRequestContext, etc.)
6. Parameter Injection - Method parameters populated (arguments, context, metadata)
7. Execution - Annotated method or specification handler invoked
8. Result Handling - Return value converted to CallToolResult
9. Serialization - Result serialized to JSON
10. Transport Response - Response sent back to client

Client-side Tool Discovery

1. Connection - Client connects to remote MCP server
2. Initialization - MCP handshake, capability negotiation
3. Tool Listing - Client requests available tools
4. Filtering - McpToolFilter applies filtering rules
5. Naming - McpToolNamePrefixGenerator creates unique names
6. Wrapping - Tools wrapped as SyncMcpToolCallback or AsyncMcpToolCallback
7. Provider - Callbacks aggregated by McpToolCallbackProvider
8. Registration - Callbacks registered with Spring AI
9. Invocation - When AI model calls tool, callback delegates to remote server
10. Change Tracking - McpToolsChangedEvent triggers cache invalidation

Native Image Support

GraalVM native image support via:

• McpHints - Runtime hints for reflection
• AOT processing for MCP schema types
• Conditional native configuration

Design Principles

1. Convention over Configuration - Sensible defaults, minimal required configuration
2. Progressive Disclosure - Start simple with annotations, use specifications for advanced needs
3. Type Safety - Compile-time checking where possible, runtime validation where needed
4. Flexibility - Multiple API levels (annotations, specifications, low-level)
5. Spring Integration - First-class Spring Boot citizen with full framework integration
6. Transport Abstraction - Transport-agnostic programming model
7. Reactive Support - Full Project Reactor integration for async operations