|
This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0! |
MCP Annotations
The Spring AI MCP Annotations module provides annotation-based method handling for Model Context Protocol (MCP) servers and clients in Java. It simplifies the creation and registration of MCP server methods and client handlers through a clean, declarative approach using Java annotations.
The MCP Annotations enable developers to create and register MCP operation handlers using declarative annotations. This approach simplifies implementing MCP server and client functionality by reducing boilerplate code and improving maintainability.
This library builds on top of the MCP Java SDK to provide a higher-level, annotation-based programming model for implementing MCP servers and clients.
Architecture
MCP defines features that the client offers, features that the server offers, and features that both use. The following diagram shows each feature with the Spring AI annotation or API that implements it. Select a feature to go to its description.
Features marked with an asterisk are available on legacy connections only; see Protocol Support.
The MCP Annotations module consists of:
Server Annotations
For MCP Servers, the following annotations are provided:
-
@McpTool- Implements MCP tools with automatic JSON schema generation -
@McpResource- Provides access to resources via URI templates -
@McpPrompt- Generates prompt messages -
@McpComplete- Provides auto-completion functionality
Client Annotations
For MCP Clients, the following annotations are provided:
-
@McpLogging- Handles logging message notifications -
@McpSampling- Handles sampling requests -
@McpElicitation- Handles elicitation requests for gathering additional information -
@McpProgress- Handles progress notifications during long-running operations -
@McpToolListChanged- Handles tool list change notifications -
@McpResourceListChanged- Handles resource list change notifications -
@McpPromptListChanged- Handles prompt list change notifications
The client annotations serve legacy connections as well as connections that speak the MCP 2026-07-28 ("modern") protocol revision, see Modern Connections.
Special Parameters and Annotations
-
McpSyncRequestContext- Special parameter type for synchronous operations that provides a unified interface for accessing MCP request context, including the original request, the server exchange, the transport context, and convenient methods for logging, progress, sampling, elicitation, and roots access. This parameter is automatically injected and excluded from JSON schema generation. Supported in Complete, Prompt, Resource, and Tool methods. A stateless server skips methods that declare it, with a warning. -
McpAsyncRequestContext- Special parameter type for asynchronous operations that provides the same unified interface asMcpSyncRequestContextbut with reactive (Mono-based) return types. This parameter is automatically injected and excluded from JSON schema generation. Supported in Complete, Prompt, Resource, and Tool methods. -
McpTransportContext- Special parameter type for stateless operations that provides lightweight access to transport-level context without full server exchange functionality. This parameter is automatically injected and excluded from JSON schema generation -
@McpProgressToken- Marks a method parameter to receive the progress token from the request. This parameter is automatically injected and excluded from the generated JSON schema. Note: When usingMcpSyncRequestContextorMcpAsyncRequestContext, the progress token can be accessed viactx.request().progressToken()instead of using this annotation. -
McpMeta- Special parameter type that provides access to metadata from MCP requests, notifications, and results. This parameter is automatically injected and excluded from parameter count limits and JSON schema generation. Note: When usingMcpSyncRequestContextorMcpAsyncRequestContext, metadata can be obtained viactx.requestMeta()instead. -
MetaProvider- Interface implemented to supply_metafield data for tool, prompt, and resource declarations. Referenced via themetaProviderattribute of@McpTool,@McpPrompt, and@McpResource.
Protocol Support
The annotations serve both generations of the protocol, the legacy revisions (2025-11-25 and earlier) and the 2026-07-28 revision. The 2026-07-28 revision has no session and no requests from the server to the client, so a few annotations and parameters apply to one generation only. See Modern or Legacy? for the differences.
| Annotation or parameter | Legacy | 2026-07-28 | Notes |
|---|---|---|---|
Server |
|||
|
Yes |
Yes |
On a 2026-07-28 server, a completion belongs to its prompt or resource template. |
|
No |
Yes |
Ignored with a warning on a legacy server. |
|
No |
Yes |
Ignored with a warning on a legacy server. |
|
Yes |
No |
There is no session to call back on. The legacy stateless server skips methods that declare them, with a warning. |
|
Yes |
No |
Use |
|
No |
Yes |
See Programming Model. |
Client |
|||
|
Yes |
Yes |
|
|
Yes |
Yes |
A 2026-07-28 connection calls them only when it sets |
|
Yes |
No |
The 2026-07-28 revision has neither sampling nor logging requests; a warning is logged at startup. |
Getting Started
Dependencies
Add the MCP annotations dependency to your project:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-annotations</artifactId>
</dependency>
The MCP annotations are automatically included when you use any of the MCP Boot Starters:
-
spring-ai-starter-mcp-client -
spring-ai-starter-mcp-client-webflux -
spring-ai-starter-mcp-server -
spring-ai-starter-mcp-server-webflux -
spring-ai-starter-mcp-server-webmvc
Quick Example
Here’s a simple example of using MCP annotations to create a calculator tool:
@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;
}
@McpTool(name = "multiply", description = "Multiply two numbers")
public double multiply(
@McpToolParam(description = "First number", required = true) double x,
@McpToolParam(description = "Second number", required = true) double y) {
return x * y;
}
}
And a simple client handler for logging:
@Component
public class LoggingHandler {
@McpLogging(clients = "my-server")
public void handleLoggingMessage(LoggingMessageNotification notification) {
System.out.println("Received log: " + notification.level() +
" - " + notification.data());
}
}
With Spring Boot auto-configuration, these annotated beans are automatically detected and registered with the MCP server or client.
Documentation
-
Client Annotations - Detailed guide for client-side annotations
-
Server Annotations - Detailed guide for server-side annotations
-
Special Parameters - Guide for special parameter types
-
Examples - Comprehensive examples and use cases