Your Simple Guide to MCP Servers: Give Your AI "Superpowers" with Spring Boot

You've built chatbots with ChatClient in this article . But how do you connect your AI to the real world so it can actually do things?

The answer is the Model Context Protocol (MCP).

If you've ever felt that connecting AI to external tools would mean building a dozen custom, one-off REST APIs for every single AI model, you're not alone. The industry saw this mess and created an open standard to simplify it. And, of course, the Spring team made it easy to implement.

In this guide, we'll walk you through building an MCP Server. You'll create a simple Spring Boot app that acts as a "tool" any compatible AI (like Claude or ChatGPT) can discover and use to get real-time weather data.

Let's give your AI some superpowers.

1. What is MCP? (The 30,000-Foot View)#

The Model Context Protocol (MCP) is an open-source standard for connecting AI applications to external systems.

The best analogy? MCP is the USB-C port for AI.

Before USB-C, we had a tangled mess of different chargers and connectors for every device. Today, one standard port can handle power, data, and video for your laptop, phone, and monitor.

MCP does the same for AI:

• The AI Host (e.g., Claude, ChatGPT): This is your "laptop." It's smart, but it needs to connect to things.
• External Systems (Databases, APIs, Local Files): These are your "peripherals" (like a hard drive, a printer, or a 3D printer).
• Your MCP Server (Our Spring App): This is the "USB-C peripheral" itself. It's a self-contained tool that tells the AI, "Hi, I'm a Weather Tool, and here are the commands I understand."
• The MCP Standard: This is the "USB-C" specification that defines how the AI Host and your server talk to each other.

You build one MCP server for your WeatherService, and any MCP-compatible AI can plug into it and start checking the weather.

2. Why Build an MCP Server with Spring AI?#

• Standardization: You're not locked in. Build your tool server once, and it can be used by Claude, ChatGPT, and any other AI that adopts the MCP standard.
• Simplicity (The Spring Way): This is the magic. Spring AI abstracts away all the messy protocol (JSON-RPC, service discovery, etc.). All you have to do is write a simple Java method and add a @Tool annotation. That's it.
• Discoverability: You don't have to manually tell the AI what your tool can do. The AI Host will ask your server, "What tools do you have?" and your Spring app will automatically respond with a list of all your @Toolannotated methods and their descriptions.
• Enterprise-Ready: You can create secure, robust servers that connect to your internal databases and services, safely exposing them to your organization's AI agents.

3. The Core Setup: Dependencies & Configuration#

Let's build our project. First, we need to add the correct dependencies and set up our properties file.

System Requirements#

• Java 17+
• Spring Boot 3.3+

pom.xml Dependencies#

You need two things: the spring-ai-starter-mcp-server and spring-web (for the tool's underlying RestClient, though the server itself won't be an HTTP server).

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

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

application.properties Configuration#

This part is CRITICAL. AI Hosts like Claude for Desktop communicate with your server using STDIO (Standard Input/Output), not HTTP. This means your app cannot write anything to stdout (like console.log or System.out.println).

Any logging will corrupt the JSON-RPC messages and break your server. We must disable all console logging that goes to stdout.

Open src/main/resources/application.properties and add this:

# 1. Turn off the Spring Boot banner. It prints to stdout.
spring.main.bannerMode=off

# 2. Set the console logging pattern to blank to prevent stdout logging.
#    (Proper logging libraries should be configured to use stderr or files).
logging.pattern.console=

4. Step 1: Create Your "Tool" (The WeatherService)#

Our "tool" is just a standard Spring @Service. The only special part is the Spring AI annotations that expose our methods to the AI.

Let's create WeatherService.java.

import org.springframework.ai.model.function.Tool;
import org.springframework.ai.model.function.ToolParam;
import org.springframework.stereotype.Service;

@Service
public class WeatherService {

    // In a real app, you'd autowire a RestClient
    // to call api.weather.gov
    // ...

    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(
        double latitude,   // Latitude coordinate
        double longitude   // Longitude coordinate
    ) {
        // Returns detailed forecast including:
        // - Temperature and unit
        // - Wind speed and direction
        // - Detailed forecast description
        
        System.err.println("LOG (to stderr): Fetching forecast for " + latitude + "," + longitude);
        
        // Dummy implementation for the blog
        return "{\\"temperature\\": 68, \\"unit\\": \\"F\\", \\"forecast\\": \\"Sunny\\"}";
    }

    @Tool(description = "Get weather alerts for a US state")
    public String getAlerts(
        @ToolParam(description = "Two-letter US state code (e.g. CA, NY)") String state
    ) {
        // Returns active alerts including:
        // - Event type
        // - Affected area
        // - Severity
        // - Description
        // - Safety instructions
        
        System.err.println("LOG (to stderr): Fetching alerts for " + state);

        // Dummy implementation
        if ("NY".equalsIgnoreCase(state)) {
            return "{\\"alert\\": \\"High-wind warning for all 5 boroughs.\\"}";
        }
        return "{\\"alert\\": \\"No active alerts.\\"}";
    }
}

Look at how simple that is!

• @Service: Makes it a normal Spring bean.
• @Tool: This is the magic. It tells Spring AI to expose this method as a "tool." The description is crucial—it's what the AI reads to understand what this tool does.
• @ToolParam: This gives the AI a description for each parameter, so it knows what kind of data to pass in.

5. Step 2: Build the MCP Server (The Main Application)#

Now we just need to tell our main Spring Boot application to find these @Tool methods and register them with the MCP server.

We do this by creating one simple @Bean.

import org.springframework.ai.model.function.MethodToolCallbackProvider;
import org.springframework.ai.model.function.ToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class McpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

    // This bean is what finds and registers all your @Tool methods
    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(weatherService)
                .build();
    }
}

The MethodToolCallbackProvider bean is auto-configured by Spring AI. We just inject our WeatherService (and any other tool services we create) into it, and it handles the rest.

6. Step 3: Running and "Connecting" Your Server to an AI#

This is the final, most important step. We'll run our server and tell an AI Host (Claude for Desktop) how to find it.

1. Build the Server

Run this in your terminal:

./mvnw clean install

This will create your server JAR file in the target/ directory (e.g., mcp-server-0.0.1-SNAPSHOT.jar).

1. Configure Your AI Host

Let's use Claude for Desktop as our "laptop." We need to tell it where our new "USB-C peripheral" is.

• Find the Claude for Desktop config file.
  • macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Open it (or create it if it doesn't exist).
• Add the following JSON. You MUST use the absolute path to your JAR file.

{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/ABSOLUTE/PATH/TO/YOUR/PROJECT/target/mcp-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Let's break this down:

• "spring-ai-mcp-weather": This is just a name we invent for our server.
• "command": "java": Tells Claude to use the java command.
• "args":
  • "-Dspring.ai.mcp.server.stdio=true": This flag tells our Spring AI app to run in STDIO mode (not HTTP).
  • "-jar": The standard Java command.
  • "/ABSOLUTE/PATH/TO/.../your.jar": The full, absolute path to the JAR you just built.

1. Restart Claude for Desktop

Save the file and completely restart your Claude for Desktop app.

That's it! Claude will now launch your Spring Boot app in the background. Your AI now has a "tool" for checking weather. You can ask it, "What are the weather alerts for NY?" and it will call your Spring Boot server to get the answer.

Conclusion: Your AI is No Longer in a Box#

You've just built a "plug-and-play" tool for the next generation of AI. You didn't write a single line of protocol code. You just wrote a Java method.

• You learned that MCP is the "USB-C for AI," a standard for connecting tools.
• You saw that a Spring AI MCP Server is just a Spring Boot app with a special starter.
• You exposed your Java methods to the world using the @Tool annotation.
• You registered your tools using a ToolCallbackProvider bean.
• You connected your "tool" to an AI Host like Claude using a simple JSON config.

The world of Generative AI is moving fast, but with Spring AI, you can build powerful, real-world tools using the Java skills you already have.