Spring AI Recipe: Creating an STDIO MCP Server

Agents are only as useful as the actions they can take. While LLMs provide reasoning and skills provide guidance, tools are what allow an agent to actually do something.

This is where Model Context Protocol (MCP) servers come in.

MCP servers expose tools that agents can invoke to interact with external systems, retrieve data, or perform actions.

In this recipe, we’ll build a simple MCP server using the STDIO transport.

NOTE: This recipe has been updated since it’s original publication to reflect changes in Spring AI 2.0.0.

MCP Servers and Tools

An MCP server provides tools that an agent can call as part of its execution loop. If skills represent what an agent knows how to do, then tools represent what an agent is capable of doing.

Creating the Project

Start by creating a new Spring Boot project and include the MCP server dependency:

implementation 'org.springframework.ai:spring-ai-starter-mcp-server'

Defining a Tool

Create a service class and annotate methods with @McpTool:

@Service
public class WeatherTools {
  @McpTool(
      name = "get-weather",
      description = "Gets the weather for a given zipcode")
  public Weather getWeatherForZipCode(
      @McpToolParam(description = "The zipcode to get the weather for.") String zipcode) {
    return new Weather(zipcode, "Sunny", "77F");
  }
}

This exposes the method as an MCP tool. For simplicity, this example returns hard-coded data. In a real-world application, this would likely call an external API.

You’ll also need a simple record type to carry the weather information:

public record Weather(
    String zipcode,
    String conditions,
    String temperature) {}

STDIO Considerations

STDIO-based MCP servers communicate via STDIN and STDOUT using JSON-RPC. Because of this any unexpected output on STDOUT can break communication. To avoid issues, disable the Spring Boot banner and reduce logging:

spring.main.banner-mode=off
logging.level.root=ERROR

Building the Server

Build the application to produce an executable JAR:

./gradlew build

Testing the Server

You can test the MCP server using tools such as:

• MCP Inspector
• MCPJam

Both tools will:

• launch your server
• communicate via STDIO
• allow you to invoke tools interactively

Example (MCP Inspector)

Configure:

• Transport Type: STDIO
• Command: java
• Arguments: -jar /path/to/stdio-mcp-server-0.0.1-SNAPSHOT.jar

Once connected:

• Navigate to the Tools tab
• Click List Tools
• Select get-weather
• Provide a zipcode
• Run the tool

You should see the result returned from the server. It will look something like this:

Invoking the MCP server’s tool in MCP Inspector

Example (MCPJam)

Setup is similar:

• Connection Type: STDIO
• Path: java -jar /path/to/stdio-mcp-server-0.0.1-SNAPSHOT.jar

Then:

• Open the Tools panel
• Select get-weather
• Enter a zipcode
• Run the tool

The following screenshot shows what this might look like:

Invoking the MCP server’s tool in MCPJam

When to Use STDIO

STDIO transport is useful when your MCP server interacts with:

• local files
• CLI tools
• browser automation
• other local system resources

However, it has limitations:

• requires distributing the JAR
• setup is more manual
• not ideal for remote or shared services

What’s Next

In many cases, it’s better to expose MCP servers over HTTP.

In the next recipe, we’ll build an MCP server using Streamable HTTP transport, which is better suited for sharing and remote access.

Get to code for this recipe and other Spring AI recipes at https://github.com/habuma/spring-ai-recipes.