Spring AI MCP Location Server Sample with WebMVC Starter

This sample project demonstrates how to create an MCP server using the Spring AI MCP Server Boot Starter with WebMVC transport. It implements a location service that exposes tools for retrieving location information using the National Location Service API.

For more information, see the MCP Server Boot Starter reference documentation.

Overview

The sample showcases:

• Integration with spring-ai-mcp-server-webmvc-spring-boot-starter
• Support for both SSE (Server-Sent Events) and STDIO transports
• Automatic tool registration using Spring AI's @Tool annotation
• Two location-related tools:
  • Convert address or city name to coordinates (latitude, longitude)
  • Convert coordinates (latitude, longitude) to address and city name
  • Get timezone information for specific coordinates (latitude, longitude)
  • Get major cities within a specific country
  • Calculate distance between two geographic points

Dependencies

The project requires the Spring AI MCP Server WebMVC Boot Starter:

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

This starter provides:

• HTTP-based transport using Spring MVC (WebMvcSseServerTransport)
• Auto-configured SSE endpoints
• Optional STDIO transport
• Included spring-boot-starter-web and mcp-spring-webmvc dependencies

Building the Project

Build the project using Maven:

./mvnw clean install -DskipTests

Running the Server

The server supports two transport modes:

WebMVC SSE Mode (Default)

java -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

STDIO Mode

To enable STDIO transport, set the appropriate properties:

java -Dspring.ai.mcp.server.stdio=true -Dspring.main.web-application-type=none -jar target/mcp-weather-starter-webmvc-server-0.0.1-SNAPSHOT.jar

Configuration

Configure the server through application.properties:

# Server identification
spring.ai.mcp.server.name=my-weather-server
spring.ai.mcp.server.version=0.0.1

# Server type (SYNC/ASYNC)
spring.ai.mcp.server.type=SYNC

# Transport configuration
spring.ai.mcp.server.stdio=false
spring.ai.mcp.server.sse-message-endpoint=/mcp/message

# Change notifications
spring.ai.mcp.server.resource-change-notification=true
spring.ai.mcp.server.tool-change-notification=true
spring.ai.mcp.server.prompt-change-notification=true

# Logging (required for STDIO transport)
spring.main.banner-mode=off
logging.file.name=./target/starter-webmvc-server.log

Available Tools

Weather Forecast Tool

• Name: getWeatherForecastByLocation
• Description: Get weather forecast for a specific latitude/longitude
• Parameters:
  • latitude: double - Latitude coordinate
  • longitude: double - Longitude coordinate

Weather Alerts Tool

• Name: getAlerts
• Description: Get weather alerts for a US state
• Parameters:
  • state: String - Two-letter US state code (e.g., CA, NY)

Server Implementation

The server uses Spring Boot and Spring AI's tool annotations for automatic tool registration:

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

    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService){
      return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
    }
}

The WeatherService implements the weather tools using the @Tool annotation:

@Service
public class WeatherService {
    @Tool(description = "Get weather forecast for a specific latitude/longitude")
    public String getWeatherForecastByLocation(double latitude, double longitude) {
        // Implementation using weather.gov API
    

... [View full README on GitHub](https://github.com/somasekharraju9/mcp-server3#readme)