Spring AI's MCP Server Boot Starter lets you expose any Spring Bean as an MCP tool — turning your existing Spring Boot services into MCP servers consumable by Claude Code, Cursor, Codex, Goose, and any other MCP client, with one dependency and a few annotations.
Why Adopt
This is one of the most high-leverage things a Java team can do right now. If you have existing Spring Boot services with business logic, you can expose that logic as MCP tools in minutes — making it instantly available to every AI agent that speaks MCP. No custom API, no glue code, no per-client integration work.
Spring joined the MCP ecosystem as a key contributor and maintains the official MCP Java SDK. The Boot Starter reached production quality with Spring AI 1.1, and the @McpTool annotation model (no manual callback registration needed) arrived in 1.1.0-M2.
The Core Pattern
Add the dependency:
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-mcp-server-spring-boot-starter</artifactId>
</dependency>
Annotate methods you want to expose as MCP tools:
@Component
public class OrderTools {
@McpTool(name = "get_order", description = "Look up an order by ID")
public OrderDetails getOrder(
@McpToolParam(description = "The order ID", required = true) String orderId
) {
return orderService.findById(orderId);
}
@McpTool(name = "list_orders",
description = "List all orders for a customer, optionally filtered by status")
public List<OrderSummary> listOrders(
@McpToolParam(description = "Customer ID", required = true) String customerId,
@McpToolParam(description = "Filter by status: pending, shipped, delivered") String status
) {
return orderService.findByCustomer(customerId, status);
}
}
Spring auto-discovers all @McpTool-annotated methods and registers them. No ToolCallbackProvider bean needed. JSON schemas for parameters are generated automatically from method signatures and @McpToolParam descriptions.
Transport Options
Configure the transport for your deployment context:
# STDIO — for local tools consumed by desktop agents (Claude Code, Cursor)
spring.ai.mcp.server.stdio=true
# Streamable HTTP — for remote/multi-client access (replaces SSE)
spring.ai.mcp.server.protocol=STREAMABLE
# SSE — legacy, still supported
spring.ai.mcp.server.protocol=SSE
STDIO is the right choice when Claude Code or Cursor will run the server as a subprocess on a developer's machine. Streamable HTTP is right for a deployed service consumed by multiple clients.
Exposing Resources (Read-Only Data)
Beyond tools, MCP servers can expose resources — documents, files, database records — that AI agents can read:
@Component
public class DocumentResources {
@McpResource(uri = "docs://runbooks/{service}",
description = "Operational runbook for a service")
public String getRunbook(@PathVariable String service) {
return runbookRepository.findByService(service);
}
}
Dynamic Tool Updates
Tools can be added or removed at runtime without restarting the server, and connected MCP clients are notified automatically:
@Autowired McpServerFeatures.AsyncToolSpecificationChangeNotifier notifier;
// When a new feature flag enables a tool:
notifier.notifyToolListChanged();
OAuth2 Security
MCP servers expose sensitive business logic and should be secured. Spring AI integrates with Spring Security to add OAuth2 protection:
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://your-auth-server/
The MCP spec 2025-03-26 formalises OAuth2 as the standard security model for MCP — Spring AI is ahead of most frameworks in implementing this.
Key Characteristics
| Property | Value |
|---|---|
| Requires | Spring AI 1.1+, Spring Boot 3.2+ |
| Transports | STDIO, SSE, Streamable HTTP |
| Auth | OAuth2 (Spring Security integration) |
| Schema generation | Automatic from method signatures |
| Dynamic tools | Yes — runtime add/remove |