Java / Gradle

MCP Weather Server with STDIO transport

Build an MCP weather server with STDIO transport.

Sergio del Amo

On this guide

In this section

Getting Started

In this guide, we will create a Micronaut application written in Java.

What you will need

To complete this guide, you will need the following:

Some time on your hands
A decent text editor or IDE (e.g. IntelliJ IDEA)
JDK 21 or greater installed with JAVA_HOME configured appropriately

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Download and unzip the source

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

What will you build?

In this guide, we will create an MCP Server with Micronaut like the one described in the Build an MCP server tutorial on the Model Context Protocol website.

Dependency

Add the Micronaut MCP Server Java SDK dependency to your build file:

build.gradle

implementation("io.micronaut.mcp:micronaut-mcp-server-java-sdk")

To use Micronaut JSON Schema generation capabilities, add the following dependencies:

build.gradle

annotationProcessor("io.micronaut.jsonschema:micronaut-json-schema-processor")
implementation("io.micronaut.jsonschema:micronaut-json-schema-annotations")

Configuration

src/main/resources/application.properties

micronaut.mcp.server.info.name=Weather
micronaut.mcp.server.info.version=0.0.1
micronaut.mcp.server.transport=STDIO

1	To use STDIO transport.

JSON Schema Generation

An MCP Tool can define its input schema using JSON Schema.

Thanks to Micronaut JSON Schema, we can generate the JSON Schema at compile-time given a Java file.

Create two Java records to model the tools' inputs.

GetAlertInput will be the input schema of the getAlerts tool.

src/main/java/example/micronaut/GetAlertInput.java

package example.micronaut;

import io.micronaut.jsonschema.JsonSchema;
import io.micronaut.serde.annotation.Serdeable;

/**
 *
 * @param state Two-letter US state code (e.g. CA, NY)
 */
@Serdeable // 
@JsonSchema // 
public record GetAlertInput(String state) {
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Annotate the class with `@JsonSchema` to generate a JSON Schema for class during build time.

Point will be the input schema of the getWeatherForecastByLocation tool.

src/main/java/example/micronaut/Point.java

package example.micronaut;

import io.micronaut.jsonschema.JsonSchema;
import io.micronaut.serde.annotation.Serdeable;

/**
 *
 * @param latitude Latitude of the location
 * @param longitude Longitude of the location
 */
@Serdeable // 
@JsonSchema // 
public record Point(double latitude, double longitude) {
}

1	Declare the `@Serdeable` annotation at the type level in your source code to allow the type to be serialized or deserialized.
2	Annotate the class with `@JsonSchema` to generate a JSON Schema for class during build time.

MCP Tool

The MCP Server exposes two tools: getWeatherForecastByLocation and getAlerts.

src/main/java/example/micronaut/Tools.java

package example.micronaut;

import example.micronaut.weather.WeatherClient;
import io.micronaut.mcp.annotations.Tool;
import jakarta.inject.Singleton;

@Singleton // 
class Tools {

    private final WeatherClient weatherClient;

    Tools(WeatherClient weatherClient) { // 
        this.weatherClient = weatherClient;
    }

    @Tool(description = "Get weather forecast for specific latitude/longitude coordinates") // 
    String getWeatherForecastByLocation(Point point) {
        return weatherClient.formattedForecast(point.latitude(), point.longitude());
    }

    @Tool(description = "Get weather alerts for a US state") // 
    String getAlerts(GetAlertInput input) {
        return weatherClient.formattedAlerts(input.state());
    }
}

1	Use `jakarta.inject.Singleton` to designate a class as a singleton.
2	Use constructor injection to inject a bean of type `WeatherClient`.
3	Annotate a method with `@Tool` to expose it as an MCP Tool.

WeatherClient is a Micronaut bean that uses the Micronaut HTTP Client to consume the https://api.weather.gov API. Please download the complete project to check the code.

STDOUT

When using the STDIO transport, it is important to ensure that the application does not write any logs or other output to stdout, as this would interfere with the MCP protocol communication.

Disable the Micronaut banner

src/main/java/example/micronaut/Application.java

package example.micronaut;

import io.micronaut.runtime.Micronaut;

public class Application {

    public static void main(String[] args) {
        Micronaut.build(args)
                 .banner(false)
                 .start();
    }
}

Configure Logback not to log to stdout. For example, you can configure Logback to log to a file or to stderr (see <target>System.err</target> in the configuration file below):

src/main/resources/logback.xml

<configuration>

    <appender name="STDERR" class="ch.qos.logback.core.ConsoleAppender">
        <target>System.err</target>
        <!-- encoders are assigned the type
             ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
        <encoder>
            <pattern>%cyan(%d{HH:mm:ss.SSS}) %gray([%thread]) %highlight(%-5level) %magenta(%logger{36}) - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="STDERR" />
    </root>
</configuration>

Executable JAR

Create an executable jar including all dependencies:

./gradlew shadowJar

MCP Inspector

To test the MCP Server, run the MCP inspector.

Select STDIO as Transport type.

Enter java as Command.

Enter -jar PATH_TO_YOUR_PROJECT/build/libs/default-0.1-all.jar as Arguments.

Click connect. You will be able to list tools and invoke the getWeatherForecastByLocation tool.

Note	The https://api.weather.gov API works only for US locations.

You will also be able to invoke the getAlerts tool.

Next Steps

Explore more features with Micronaut Guides.

Check the Micronaut MCP documentation and the Micronaut MCP Guides

License

Note	All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images).