Spring AI MCP: Build & Deploy Java MCP Servers (2026)

Spring AI MCP is reshaping how Java teams connect enterprise services to AI agents. With the Model Context Protocol becoming the standard interface between LLMs and external tools, Spring Boot developers finally have a first-class framework for building MCP servers and clients in Java. But the gap between a working demo and a production deployment is wider than most tutorials admit.

We analyzed over 50 developer discussions where Java and Spring teams share what actually works when building MCP integrations. The result is this guide, covering everything from your first @Tool annotation to production gateway architecture.

What Is Spring AI MCP and Why Does It Matter?

Spring AI MCP is Spring's native integration with the Model Context Protocol, a standardized way for AI models to discover and invoke external tools, access resources, and use prompt templates through a structured client-server architecture. It provides Java developers with annotation-driven server creation, auto-configured client connections, and multiple transport options, all built on top of Spring Boot conventions.

Why does this matter for Java teams? Three reasons.

First, MCP adoption is accelerating fast. One platform engineering manager reported that "MCP adoption went from zero to everywhere in 3 months," with 14 servers appearing across their org before anyone had a chance to set standards. If your team builds AI-powered products, MCP integration is becoming table stakes.

Second, the Java ecosystem has unique gravity. Despite heated community debates about whether Java belongs in AI, the counterargument is compelling: there are millions of Spring Boot services already running in production. Teams are not rewriting their stack in Python just to add MCP capabilities. Spring AI lets you expose existing services as MCP tools with minimal changes.

Third, MCP Spring AI bridges the gap between chat-based AI and your existing APIs. Instead of building custom integrations for every LLM client, you build one MCP server and it works with Claude Desktop, VS Code, Cursor, Gemini CLI, and any other MCP-compatible host.

Building Your First Spring AI MCP Server

The fastest path to a working Spring AI MCP server example starts with the right starter dependency. Add spring-ai-starter-mcp-server-webmvc to your Maven or Gradle project to get SSE transport with Spring MVC.

Maven Setup

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

For reactive applications, swap in spring-ai-starter-mcp-server-webflux instead.

Defining Tools with Spring AI MCP Annotations

Spring AI MCP annotations make tool creation straightforward. Define a Spring bean, annotate methods with @Tool, and Spring AI handles the MCP protocol plumbing.

@Service
public class WeatherService {
 
    @Tool(description = "Get current weather for a city")
    public WeatherResponse getWeather(String city) {
        // Your implementation here
        return weatherClient.fetch(city);
    }
}

This spring boot mcp server example registers a tool that any MCP client can discover and call. Spring AI automatically generates the JSON schema from your method signature and exposes it through the MCP server protocol.

Configure your application.yml to set the server name and transport:

spring:
  ai:
    mcp:
      server:
        name: weather-service
        version: 1.0.0

That is a complete, working spring ai mcp server. One developer on r/SpringBoot summarized the experience well: "It's so easy that I had to fact check it many times because I couldn't believe I only had to rewrite the controller class."

The Transport Trap That Catches Everyone

Here is where most developers hit their first wall. We found this to be the single most discussed pain point across community forums, appearing in at least 8 separate threads.

The problem: Spring Boot's MCP SDK defaults to SSE (Server-Sent Events) transport. But CLI-based MCP clients like Claude Code and Gemini CLI expect stdio transport, configured via a command in settings.json, not a URL.

As one experienced developer explained: "Spring Boot MCP SDK defaults to SSE transport, but CLI clients like Claude Code and Gemini expect stdio configured via a command in settings.json, not a URL."

Another developer reported being "pretty lost with all the MCP protocol variations (SSE, HTTP, etc.) and especially how these are supposed to be defined/configured in VSCode." Their Spring AI server appeared healthy in logs, showing "Creating new SSE connection for session," but the MCP handshake never completed.

The fix depends on your target client:

• For web/IDE clients (VS Code, Cursor, Continue.dev): SSE works. Use spring-ai-starter-mcp-server-webmvc.
• For CLI clients (Claude Code, Gemini CLI): You need stdio transport. Use spring-ai-starter-mcp-server (without webmvc) and configure the client to launch your server as a subprocess.
• For both: Consider running dual transports or using a gateway that normalizes the connection. You can choose transport for your Java implementation based on your client requirements.

Spring AI MCP Client: Connecting to MCP Servers

Building an MCP server is only half the equation. Spring AI also provides a spring ai mcp client that lets your Java application consume tools from any MCP server.

Client Setup

Add the spring-ai-starter-mcp client dependency:

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

Then configure connections in application.yml:

spring:
  ai:
    mcp:
      client:
        servers:
          weather:
            url: http://localhost:8080
            transport: sse
          database:
            command: java -jar db-mcp-server.jar
            transport: stdio

This spring ai mcp client example shows connecting to two servers simultaneously, one over SSE and one over stdio. The client auto-discovers available tools from each server and makes them available to your AI chat functions.

Multi-Server Configuration

In practice, your AI application will connect to multiple MCP servers. Spring AI handles this natively. Each server connection is independent, with its own transport and lifecycle. The client aggregates all discovered tools into a unified tool registry that your LLM can query.

This is where you start to see the value of building on mcp spring ai rather than rolling your own protocol integration. The framework handles connection management, tool discovery, schema validation, and error recovery out of the box.

Transport Options: SSE vs Stdio vs Streamable HTTP

Choosing the right transport is one of the most consequential decisions in your spring ai mcp architecture. Each option serves different deployment scenarios.

When SSE Breaks Down

SSE works well for single-client scenarios, but it has limitations. Each SSE connection holds an open HTTP connection. Under heavy agent traffic, this can exhaust connection pools. Community research confirmed this: one developer reported that "STDIO fails catastrophically under concurrent load (20 of 22 requests failed with just 20 simultaneous connections)," and SSE, while better, still requires careful connection management.

Spring AI MCP Streamable HTTP

The newer spring ai mcp streamable-http transport, supported through spring-ai-starter-mcp-server-webflux, uses standard HTTP requests with optional streaming. It handles concurrent connections more gracefully and works well behind load balancers and API gateways.

For production deployments serving multiple agents, streamable HTTP is the recommended path. It combines the remote accessibility of SSE with better scalability characteristics.

We analyzed developer discussions where teams share their transport decisions. The pattern is clear: teams that start with stdio for local development and migrate to streamable HTTP for production, with a gateway handling client-side transport differences, report the fewest integration issues. For a deeper breakdown of transport tradeoffs, see our guide on choosing transport for your Java implementation.

Taking Spring AI MCP to Production

Getting a spring ai mcp example running locally is straightforward. Getting a spring boot ai mcp server into production is where most teams struggle. We analyzed 15+ community threads focused specifically on production MCP deployments, and the challenges fall into three categories: authentication, deployment architecture, and governance.

Authentication Patterns

Authentication is the hardest unsolved problem in MCP production deployments. Community discussions reveal three common approaches, each with real tradeoffs.

Per-server OAuth: Each MCP server validates tokens independently. This works for small setups but creates maintenance overhead at scale. As one engineering lead described it: "The guy who built our proxy left 3 months ago and nobody fully understands it now." Every new server needs the same boilerplate, and updating a permission means touching multiple codebases.

API keys: The simplest option, and what most teams default to. But API keys lack granularity. One developer pointed out a fundamental flaw: "Once an agent authenticates, it can call any tool on the server. There's no per-tool policy."

Gateway-managed auth: A centralized gateway handles authentication and authorization for all MCP servers behind it. Teams that tested all three approaches reported that the gateway pattern won on maintainability, with roughly 8ms of added latency per tool call, which is noise compared to typical LLM response times.

The deeper issue is that OAuth token lifecycles do not match agent lifecycles. As one infrastructure engineer put it: "OAuth breaks in MCP because token lifecycle doesn't match agent lifecycle." Agents run long sessions. Tokens expire. Recovery mid-execution is fragile. Teams working around this with custom token rotation describe it as a constant operational burden: "I had to do a custom implementation for OAuth2. It rotates them tokens every twelve hours."

Deployment Architecture

For containerized deployments, package your Spring AI MCP server as a standard Docker image and deploy to Cloud Run, ECS, or Kubernetes. The key considerations:

• Use streamable HTTP transport for remote servers (not stdio)
• Configure health checks on the MCP endpoint
• Set connection timeouts appropriate for LLM tool-call patterns (longer than typical REST APIs)
• Use direct database connections (not pooled) for worker-pattern servers

To deploy your Java server to cloud infrastructure, a gateway in front of your MCP servers provides routing, load balancing, and a single endpoint for all clients.

Gateway Architecture for Enterprise

As MCP adoption scales within an organization, governance becomes critical. Platform teams report the same pattern: MCP servers proliferate fast, duplicates emerge, and nobody has a central view of what tools exist.

A gateway like Apigene sits between your AI clients and your MCP servers, providing:

• Centralized auth and audit: One authentication layer for all servers, with logs showing which agent called which tool
• Dynamic tool loading: Expose only the tools each agent needs, reducing token costs and hallucination risk
• Transport normalization: Clients connect via their preferred transport, and the gateway handles the translation
• Rich UI rendering: Apigene's MCP Apps standard returns interactive UI components inside ChatGPT and Claude, not just text responses

For enterprise use cases perfect for Spring AI + MCP, a gateway is not optional. It is the difference between a collection of demo servers and a managed tool infrastructure. You can apply production MCP rules to your Spring AI integration and route your Spring AI server through a gateway to get these capabilities without changing your server code.

Spring AI MCP vs Other Frameworks

When building an mcp server java integration, Spring AI is not your only option. Here is how it compares to alternatives.

For teams already on Spring Boot, Spring AI MCP is the clear choice. It follows Spring conventions (auto-configuration, starters, annotations) and integrates with the existing Spring ecosystem.

For teams evaluating Spring AI vs LangChain for MCP integration, the decision often comes down to existing stack: if you are a Spring shop, Spring AI is a natural fit. If you are framework-agnostic and want broader language model support, LangChain4j offers more flexibility at the cost of more manual configuration.

Understanding the broader difference between MCP tools vs AI agents in Java architectures also helps frame the role of Spring AI MCP in your stack.

Common Pitfalls and How to Fix Them

We analyzed failure patterns reported across dozens of community threads. Here are the most frequent issues Java developers face with Spring AI MCP, and how to resolve them.

Transport Mismatch

The most common issue, mentioned in 8+ separate threads. Your Spring AI MCP server uses SSE, but your CLI client expects stdio. Symptoms: connection hangs, 404 errors during initialization, or the client reports "Waiting for server to respond to initialize request."

Fix: Match your starter dependency to your target client. Use spring-ai-starter-mcp-server-webmvc for SSE clients, spring-ai-starter-mcp-server for stdio. When supporting multiple client types, deploy behind a gateway or run dual transports.

OAuth Token Expiry During Agent Sessions

Agents run longer than typical API consumers. A 1-hour token works fine for a REST client making short requests but fails mid-conversation when an agent chains 20 tool calls over 45 minutes.

Fix: Implement proactive token refresh, or manage auth at the gateway level where token lifecycle is handled independently of individual server sessions.

MCP Server Sprawl

As one platform team manager reported: "I count 14 MCP servers across the org, at least 4 are duplicates built by different teams who didn't know the other existed." Without a central registry, teams build redundant servers and inconsistent auth patterns emerge.

Fix: Establish an internal MCP server catalog early. Use a gateway as the discovery layer so teams can find existing tools before building new ones.

Tool Count Explosion

Loading too many tools into a single MCP server degrades LLM performance. Community consensus from developers and tool builders: even 60 tools is too many for a single server. The model spends tokens parsing tool descriptions instead of solving the problem.

Fix: Segment tools into focused, domain-specific servers. Use virtual toolsets at the gateway level to expose only the tools each agent needs. To debug your Java MCP server and inspect which tools are being loaded, use the MCP Inspector or equivalent tooling.

The Bottom Line

Spring AI MCP gives Java developers a production-grade path to building MCP servers and clients. The framework handles the protocol complexity. Your job is to make the right architectural decisions: choose the right transport, centralize auth through a gateway, and resist the temptation to expose 100 tools from a single server.

The teams reporting the most success follow a clear pattern: start with Spring AI for the server logic, add a gateway like Apigene for auth, routing, and tool management, and invest in observability from day one.

MCP is moving fast. Spring AI's integration is maturing with every release. If your organization runs Java in production, this is the path to connecting those services to AI agents without rewriting your stack.