This version is still in development and is not considered stable yet. For the latest snapshot version, please use Spring AI 1.1.3!spring-doc.cn

Model Context Protocol (MCP)

New to MCP? Start with our Getting Started with MCP guide for a quick introduction and hands-on examples.

The Model Context Protocol (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured way. Think of it as a bridge between your AI models and the real world - allowing them to access databases, APIs, file systems, and other external services through a consistent interface. It supports multiple transport mechanisms to provide flexibility across different environments.spring-doc.cn

The MCP Java SDK provides a Java implementation of the Model Context Protocol, enabling standardized interaction with AI models and tools through both synchronous and asynchronous communication patterns.spring-doc.cn

Spring AI embraces MCP with comprehensive support through dedicated Boot Starters and MCP Java Annotations, making it easier than ever to build sophisticated AI-powered applications that can seamlessly connect to external systems. This means Spring developers can participate in both sides of the MCP ecosystem - building AI applications that consume MCP servers and creating MCP servers that expose Spring-based services to the wider AI community. Bootstrap your AI applications with MCP support using Spring Initializer.spring-doc.cn

MCP Java SDK Architecture

This section provides an overview for the MCP Java SDK architecture. For the Spring AI MCP integration, refer to the Spring AI MCP Boot Starters documentation.

The Java MCP implementation follows a three-layer architecture that separates concerns for maintainability and flexibility:spring-doc.cn

Figure 1. MCP Stack Architecture

Client/Server Layer (Top)

The top layer handles the main application logic and protocol operations:spring-doc.cn

McpClient - Manages client-side operations and server connectionsspring-doc.cn
McpServer - Handles server-side protocol operations and client requestsspring-doc.cn
Both components utilize the session layer below for communication managementspring-doc.cn

Session Layer (Middle)

The middle layer manages communication patterns and maintains connection state:spring-doc.cn

McpSession - Core session management interfacespring-doc.cn
McpClientSession - Client-specific session implementationspring-doc.cn
McpServerSession - Server-specific session implementationspring-doc.cn

Transport Layer (Bottom)

The bottom layer handles the actual message transport and serialization:spring-doc.cn

McpTransport - Manages JSON-RPC message serialization and deserializationspring-doc.cn
Supports multiple transport implementations (STDIO, HTTP/SSE, Streamable-HTTP, etc.)spring-doc.cn
Provides the foundation for all higher-level communicationspring-doc.cn

MCP Client
The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:spring-doc.cn Protocol version negotiation to ensure compatibility with serversspring-doc.cn Capability negotiation to determine available featuresspring-doc.cn Message transport and JSON-RPC communicationspring-doc.cn Tool discovery and executionspring-doc.cn Resource access and managementspring-doc.cn Prompt system interactionsspring-doc.cn Optional features:spring-doc.cn Roots managementspring-doc.cn Sampling supportspring-doc.cn Synchronous and asynchronous operationsspring-doc.cn Transport options:spring-doc.cn Stdio-based transport for process-based communicationspring-doc.cn Java HttpClient-based SSE client transportspring-doc.cn WebFlux SSE client transport for reactive HTTP streamingspring-doc.cn

MCP Client

The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:spring-doc.cn

Protocol version negotiation to ensure compatibility with serversspring-doc.cn
Capability negotiation to determine available featuresspring-doc.cn
Message transport and JSON-RPC communicationspring-doc.cn
Tool discovery and executionspring-doc.cn
Resource access and managementspring-doc.cn
Prompt system interactionsspring-doc.cn
Optional features:spring-doc.cn
- Roots managementspring-doc.cn
- Sampling supportspring-doc.cn
Synchronous and asynchronous operationsspring-doc.cn
Transport options:spring-doc.cn
- Stdio-based transport for process-based communicationspring-doc.cn
- Java HttpClient-based SSE client transportspring-doc.cn
- WebFlux SSE client transport for reactive HTTP streamingspring-doc.cn

MCP Server
The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:spring-doc.cn Server-side protocol operations implementationspring-doc.cn Tool exposure and discoveryspring-doc.cn Resource management with URI-based accessspring-doc.cn Prompt template provision and handlingspring-doc.cn Capability negotiation with clientsspring-doc.cn Structured logging and notificationsspring-doc.cn Concurrent client connection managementspring-doc.cn Synchronous and Asynchronous API supportspring-doc.cn Transport implementations:spring-doc.cn Stdio, Streamable-HTTP, Stateless Streamable-HTTP, SSEspring-doc.cn

MCP Server

The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:spring-doc.cn

Server-side protocol operations implementationspring-doc.cn
- Tool exposure and discoveryspring-doc.cn
- Resource management with URI-based accessspring-doc.cn
- Prompt template provision and handlingspring-doc.cn
- Capability negotiation with clientsspring-doc.cn
- Structured logging and notificationsspring-doc.cn
Concurrent client connection managementspring-doc.cn
Synchronous and Asynchronous API supportspring-doc.cn
Transport implementations:spring-doc.cn
- Stdio, Streamable-HTTP, Stateless Streamable-HTTP, SSEspring-doc.cn

For detailed implementation guidance, using the low-level MCP Client/Server APIs, refer to the MCP Java SDK documentation. For simplified setup using Spring Boot, use the MCP Boot Starters described below.spring-doc.cn

Spring AI MCP Integration

Spring AI provides MCP integration through the following Spring Boot starters:spring-doc.cn

Client Starters

spring-ai-starter-mcp-client - Core starter providing STDIO, Servlet-based Streamable-HTTP, Stateless Streamable-HTTP and SSE supportspring-doc.cn
spring-ai-starter-mcp-client-webflux - WebFlux-based Streamable-HTTP, Stateless Streamable-HTTP and SSE transport implementationspring-doc.cn

Server Starters

STDIO

Server Type Dependency Property

Server Type	Dependency	Property
Standard Input/Output (STDIO)spring-doc.cn	`spring-ai-starter-mcp-server`spring-doc.cn	`spring.ai.mcp.server.stdio=true`spring-doc.cn

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 WebMVC spring-doc.cn

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

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

Streamable-HTTP WebMVC spring-doc.cn

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

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

Stateless Streamable-HTTP WebMVC spring-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 WebFlux spring-doc.cn

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

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

Streamable-HTTP WebFlux spring-doc.cn

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

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

Stateless Streamable-HTTP WebFlux spring-doc.cn

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

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

Spring AI MCP Annotations

In addition to the programmatic MCP client & server configuration, Spring AI provides annotation-based method handling for MCP servers and clients through the MCP Annotations module. This approach simplifies the creation and registration of MCP operations using a clean, declarative programming model with Java annotations.spring-doc.cn

The MCP Annotations module enables developers to:spring-doc.cn

Create MCP tools, resources, and prompts using simple annotationsspring-doc.cn
Handle client-side notifications and requests declarativelyspring-doc.cn
Reduce boilerplate code and improve maintainabilityspring-doc.cn
Automatically generate JSON schemas for tool parametersspring-doc.cn
Access special parameters and context informationspring-doc.cn

Key features include:spring-doc.cn

Server Annotations: @McpTool, @McpResource, @McpPrompt, @McpCompletespring-doc.cn
Client Annotations: @McpLogging, @McpSampling, @McpElicitation, @McpProgressspring-doc.cn
Special Parameters: McpSyncServerExchange, McpAsyncServerExchange, McpTransportContext, McpMetaspring-doc.cn
Automatic Discovery: Annotation scanning with configurable package inclusion/exclusionspring-doc.cn
Spring Boot Integration: Seamless integration with MCP Boot Startersspring-doc.cn

Upgrading to Spring AI 2.0

Starting with Spring AI 2.0, the Spring-specific MCP transport implementations (mcp-spring-webflux and mcp-spring-webmvc) are no longer shipped by the MCP Java SDK. They have been moved into the Spring AI project itself. This is a breaking change that requires dependency and import updates for applications that directly reference these transport artifacts or classes.spring-doc.cn

Maven Dependency Group ID Change

The mcp-spring-webflux and mcp-spring-webmvc artifacts have moved from the io.modelcontextprotocol.sdk group to org.springframework.ai.spring-doc.cn

Before (MCP Java SDK < 1.0.x and Spring AI < 2.0.x)

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webflux</artifactId>
</dependency>

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-spring-webmvc</artifactId>
</dependency>

After (MCP Java SDK >= 1.0.x and Spring AI >= 2.0.x)

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

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

When using the spring-ai-bom or the Spring AI starter dependencies (spring-ai-starter-mcp-server-webflux, spring-ai-starter-mcp-server-webmvc, spring-ai-starter-mcp-client-webflux) no explicit version is needed — the BOM manages it automatically.

Java Package Relocation

All transport classes have been relocated to org.springframework.ai packages.spring-doc.cn

Table 1. Server transport classes
Class	Old package (MCP SDK)	New package (Spring AI)
`WebFluxSseServerTransportProvider`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webflux.transport`spring-doc.cn
`WebFluxStreamableServerTransportProvider`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webflux.transport`spring-doc.cn
`WebFluxStatelessServerTransport`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webflux.transport`spring-doc.cn
`WebMvcSseServerTransportProvider`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webmvc.transport`spring-doc.cn
`WebMvcStreamableServerTransportProvider`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webmvc.transport`spring-doc.cn
`WebMvcStatelessServerTransport`spring-doc.cn	`io.modelcontextprotocol.server.transport`spring-doc.cn	`org.springframework.ai.mcp.server.webmvc.transport`spring-doc.cn

Table 2. Client transport classes
Class	Old package (MCP SDK)	New package (Spring AI)
`WebFluxSseClientTransport`spring-doc.cn	`io.modelcontextprotocol.client.transport`spring-doc.cn	`org.springframework.ai.mcp.client.webflux.transport`spring-doc.cn
`WebClientStreamableHttpTransport`spring-doc.cn	`io.modelcontextprotocol.client.transport`spring-doc.cn	`org.springframework.ai.mcp.client.webflux.transport`spring-doc.cn

Example import update

// Before
import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
import io.modelcontextprotocol.server.transport.WebMvcSseServerTransportProvider;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.client.transport.WebClientStreamableHttpTransport;

// After
import org.springframework.ai.mcp.server.webflux.transport.WebFluxSseServerTransportProvider;
import org.springframework.ai.mcp.server.webmvc.transport.WebMvcSseServerTransportProvider;
import org.springframework.ai.mcp.client.webflux.transport.WebFluxSseClientTransport;
import org.springframework.ai.mcp.client.webflux.transport.WebClientStreamableHttpTransport;

MCP SDK Version Requirement

Spring AI 2.0 requires MCP Java SDK 1.0.0 (RC1 or later). The SDK version has been bumped from 0.18.x to the 1.0.x release line. Update your BOM or explicit version accordingly.spring-doc.cn

Spring Boot Auto-configuration Users

If you rely exclusively on Spring Boot auto-configuration via the Spring AI starters, you do not need to change any Java code. The auto-configurations have already been updated internally to reference the new packages. Only update your pom.xml/build.gradle dependency coordinates as described above.spring-doc.cn

Model Context Protocol (MCP)

MCP Java SDK Architecture

Client/Server Layer (Top)

Session Layer (Middle)

Transport Layer (Bottom)

Spring AI MCP Integration

Client Starters

Server Starters

STDIO

WebMVC

WebMVC (Reactive)

Spring AI MCP Annotations

Upgrading to Spring AI 2.0

Maven Dependency Group ID Change

Java Package Relocation

MCP SDK Version Requirement

Spring Boot Auto-configuration Users

Additional Resources