Java / Maven

MCP Weather Server with HTTP transport

Build an MCP weather server with HTTP 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:

pom.xml

<dependency>
    <groupId>io.micronaut.mcp</groupId>
    <artifactId>micronaut-mcp-server-java-sdk</artifactId>
    <scope>compile</scope>
</dependency>

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

pom.xml

<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.jsonschema</groupId>
    <artifactId>micronaut-json-schema-processor</artifactId>
</path>
<dependency>
    <groupId>io.micronaut.jsonschema</groupId>
    <artifactId>micronaut-json-schema-annotations</artifactId>
    <scope>compile</scope>
</dependency>

Configuration

src/main/resources/application.properties

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

1	To use Streamable HTTP

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.

MCP Inspector

To test the MCP Server, run the MCP inspector.

Select Streamable HTTP as Transport type.

Enter http://localhost:8080/mcp as the URL.

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).