# How to Build an MCP Server with Java Spring Boot

Building an MCP server with Java Spring Boot lets you use the Model Context Protocol within the Spring ecosystem. Enterprise Java teams can use a familiar framework to give AI models access to tools and data. With Spring AI, you can turn standard Java methods into AI tools with simple annotations, connecting older enterprise systems to modern LLMs.

Source: https://fast.io/resources/mcp-server-java-spring-boot/
Last reviewed: 2026-02-09

## What is a Spring Boot MCP Server?

A Spring Boot MCP server is a Java app that uses the Model Context Protocol to share local resources, prompts, and tools with AI clients like Claude Desktop. While many MCP servers use Python, building one in Java lets you use the reliable Spring ecosystem. You can reuse your existing services, security settings, and database connections. Spring AI recently added MCP support with the `spring-ai-mcp-server-spring-boot-starter`. This means Java developers can join the agentic AI ecosystem without learning a new language. The starter handles JSON-RPC communication over Stdio or SSE, so you can focus on writing your tools. This is helpful in enterprise environments where business logic is already tied to Java services. Using Spring's dependency injection and auto-configuration, you can connect your current databases and APIs to AI models through the Model Context Protocol.

Helpful references: [Fastio Workspaces](/product/workspaces/), [Fastio Collaboration](/product/collaboration/), and [Fastio AI](/product/ai/).

## Prerequisites for Java MCP Development

Make sure your development environment is ready before you start. Spring AI’s MCP support needs Java 17 and Spring Boot 3.x. This setup ensures your server is fast and secure, using the latest updates from the Java community. Using Spring Boot 3 also makes it easier to package your app for Kubernetes or other cloud platforms.

**Required Environment:**
*   **Java Development Kit (JDK)**: Version 17 or higher (JDK 21 is recommended for virtual threads support).
*   **Spring Boot**: Version 3.3.0 or newer.
*   **Build Tool**: Maven 3.8+ or Gradle 8.x.
*   **IDE**: IntelliJ IDEA or Eclipse with Spring Tools. You will also need an MCP client to test your server. The **Claude Desktop App** is the standard tool for local testing, as it can connect to local MCP servers defined in its configuration file.

## Step 1: Configure Dependencies

Start by creating a new Spring Boot project using Spring Initializr. Select the "Web" dependency if you plan to use Server-Sent Events (SSE), or just the core starter for standard input/output (Stdio) communication. Add the Spring AI Bill of Materials (BOM) and the MCP server starter to your `pom.xml`.

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0-SNAPSHOT</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

If you are building a CLI-based server that runs via Stdio (standard input/output), use `spring-ai-starter-mcp-server-stdio` instead of `webmvc`. Consider how this fits into your broader workflow and what matters most for your team. The right choice depends on your specific requirements: file types, team size, security needs, and how you collaborate with external partners. Testing with a free account is the fast way to know if a tool works for you.

## Step 2: Create AI Tools with Annotations

The core of an MCP server is the "Tool," which is a specific function that an AI model can execute. Spring AI simplifies this by mapping Java methods to tools using the `@Tool` annotation. Create a service class and annotate the methods you want to expose. The `@Tool` description is critical; it tells the LLM when and how to use the function.

```java
package com.example.mcpserver;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;

@Service
public class WeatherService {

@Tool(description = "Get the current weather for a specific city. Input should be a city name.")
    public String getWeather(String city) {
        // Logic to fetch weather (e.g., call an external API)
        return "The weather in " + city + " is sunny, 25°C";
    }
    
    @Tool(description = "Calculate the mortgage payment based on principal, rate, and term.")
    public double calculateMortgage(double principal, double rate, int years) {
        // Mortgage calculation logic
        return principal * rate / (1 - Math.pow(1 + rate, -years * 12));
    }
}
```

Spring Boot automatically finds these `@Tool` annotations and registers them. You don't have to do it manually. This discovery process works just like other Spring features and cuts down on boilerplate code. When an AI model calls a tool, Spring AI handles the data types and arguments, making sure they match your Java method exactly.

## Step 3: Connect Fastio for Persistent Storage

MCP servers often need to read or write files, including logs, generated reports, or code artifacts. While you can use the local file system, local files are trapped on your machine. For production agents, connect your Java MCP server to Fastio. This gives your agent a cloud-based file system that stays active between restarts and handles files up to 250GB.

**Why Fastio for Java Agents:**
*   **Persistence**: Files survive server restarts and deployments.
*   **Shared State**: Multiple agent instances can read/write the same dataset using file locks.
*   **Universal Access**: Humans can view the files the agent creates via a branded web portal. You can connect Fastio using the standard S3 adapter for Java, or run the Fastio MCP server alongside your custom server.

## Step 4: Configure and Run

Configure your server properties in `application.properties`. If you are using the WebMVC starter, you need to define the endpoint.

```properties
spring.application.name=my-java-mcp-server
spring.ai.mcp.server.transport=sse
spring.ai.mcp.server.sse.path=/mcp/message
server.port=8080
```

Build and run your application:

```bash
./mvnw spring-boot:run
```

Your server is now listening for MCP connections at `http://localhost:8080/mcp/message`. Consider how this fits into your broader workflow and what matters most for your team. The right choice depends on your specific requirements: file types, team size, security needs, and how you collaborate with external partners. Testing with a free account is the fast way to know if a tool works for you. Consider how this fits into your broader workflow and what matters most for your team. The right choice depends on your specific requirements: file types, team size, security needs, and how you collaborate with external partners. Testing with a free account is the fast way to know if a tool works for you.

## Testing with Claude Desktop

To verify your Java MCP server works, connect it to the Claude Desktop App. Edit your `claude_desktop_config.json` file. For an **SSE (Server-Sent Events)** server:

```json
{
  "mcpServers": {
    "java-spring-boot": {
      "command": "",
      "url": "http://localhost:8080/mcp/message"
    }
  }
}
```

Restart Claude. You should see a generic plug icon indicating the server is connected. Ask Claude: *"What tools do you have available?"* It should list your `getWeather` and `calculateMortgage` tools. Consider how this fits into your broader workflow and what matters most for your team. The right choice depends on your specific requirements: file types, team size, security needs, and how you collaborate with external partners. Testing with a free account is the fast way to know if a tool works for you.

## Frequently asked questions

### Can I use Spring Boot 2 for MCP servers?

No, Spring AI needs Spring Boot 3.2 and Java 17 or newer. The MCP features use modern Spring capabilities that aren't available in Spring Boot 2.x.

### Is Java good for building MCP servers?

Yes, especially for enterprise work. Java provides type safety, reliable libraries, and better performance for complex tasks than Python. It lets teams turn existing business logic into AI tools without starting from scratch.

### How do I secure a Spring Boot MCP server?

You can use Spring Security to protect your MCP endpoints. For SSE, you can use standard OAuth2 or Basic Auth. Local Stdio servers just use the security permissions of the user running the process.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.