|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
Model Context Protocol (MCP)
The Model Context Protocol (MCP) is an open protocol through which AI applications use tools, resources and prompts that other programs provide. An MCP server offers them, and an MCP client, inside the AI application, calls them.
Spring AI supports both sides. Your application can use the tools of MCP servers as if they were its own, and it can offer its own tools, resources and prompts as an MCP server.
Your application is the MCP host.
It has one MCP client for each server it connects to, and its ChatClient uses the tools of all of them.
Each server wraps a service and is built once, by the provider of that service.
So M applications and N services need M + N integrations instead of M × N: each application speaks MCP once, and each service offers it once.
| New to MCP? The Build and Use an MCP Server tutorial builds a server and a client step by step. |
What Spring AI Adds
Spring AI builds on the MCP Java SDK, which implements the protocol. On top of it, Spring AI provides:
-
Spring Boot starters that create MCP clients from configuration properties, and MCP servers from your beans.
-
A bridge to Spring AI tools: the tools of MCP servers become
ToolCallbackinstances that aChatClientcan use, and yourToolCallbackbeans become the tools of your MCP server. -
MCP annotations, such as
@McpTooland@McpResourcefor servers, and@McpElicitationfor clients. -
Spring WebMVC and WebFlux transports for MCP servers.
The community project MCP Security adds OAuth 2.0 and API key security to Spring AI MCP servers and clients, see MCP Security.
Modern or Legacy?
MCP has two generations, and Spring AI supports both:
-
Modern, the 2026-07-28 revision of the specification. There is no handshake and no session, and every request stands alone.
-
Legacy, the 2025-11-25 revision and earlier ones. Client and server set up a session with an
initializehandshake.
Legacy does not mean deprecated: both generations are supported, and one application can use both. The two generations cannot talk to each other, so choose the one that the other side speaks. A modern client cannot call a legacy server, and a legacy client cannot call a modern server.
| Legacy | Modern (2026-07-28) | |
|---|---|---|
Lifecycle |
An |
None. Every request carries the protocol version and the client capabilities. |
Input from the user |
The server sends elicitation, sampling and roots requests to the client. |
The server answers that it needs input, and the client sends the request again with the answers. The Spring AI client supports elicitation, but not sampling. |
Scaling a server |
Sessions live in the server process, except on the stateless server. |
Any server instance can answer any request. |
Clients per connection |
One client, shared by all requests. |
One client per request by default, configurable with |
Client configuration |
Every connection, unless it sets |
A Streamable HTTP connection with |
Server configuration |
|
|
Guides |
The annotations and the ToolCallback bridge work the same with both generations.
A few annotations and parameters apply to one generation only, see Protocol Support.
The 2026-07-28 revision requires the MCP Java SDK 2.2.0 line or later, which is the version that Spring AI uses by default.
|
Starters
Client
| Starter | Transports |
|---|---|
|
STDIO, and Streamable HTTP and SSE (deprecated) through the JDK |
|
STDIO, and Streamable HTTP and SSE (deprecated) through the WebFlux |
Modern connections use the JDK HttpClient transport with both starters.
See MCP Client.
Server
| Starter | Transport | Selected with |
|---|---|---|
|
STDIO |
|
|
HTTP on Spring WebMVC |
|
|
HTTP on Spring WebFlux |
|
Set spring.ai.mcp.server.protocol explicitly, for example to STREAMABLE.
Without the property, the WebMVC and WebFlux starters select the deprecated SSE transport.
See MCP Server.
The MCP Java SDK
The starters create and configure the clients and servers of the MCP Java SDK. To customize them beyond the configuration properties, or to use them without Spring Boot, see the SDK documentation:
-
Overview, which describes the architecture of both generations.
-
MCP Client and MCP Server for the legacy generation.
In This Section
-
MCP Client connects your application to MCP servers.
-
MCP Server exposes your tools, resources and prompts.
-
MCP Annotations declare server features and client handlers on methods.
-
MCP Security protects servers and authorizes clients.
-
MCP Utilities convert between MCP tools and Spring AI tools.
-
Using MCP Tools passes the tools of MCP servers to a
ChatClient. -
MCP Changes in Spring AI 2.0 lists what changed in 2.0.