🦄 Unicorn MCP Server

A Spring AI MCP (Model Context Protocol) server that exposes unicorn rental tools — pricing calculator, booking management, and date/time utilities — over Streamable HTTP transport.

Tech Stack

• Java 21, Spring Boot 3.5.0, Spring AI 1.1.2
• MCP Server (WebMVC / Streamable HTTP)
• H2 database (file-based) + Spring Data JPA

Tools Exposed

Prerequisites

• Java 21+
• Maven 3.9+

Build & Run

./mvnw clean package
./mvnw spring-boot:run

Server starts on http://localhost:8083. MCP endpoint: http://localhost:8083/mcp

How to Build an MCP Server (or Convert an Existing Codebase)

If you're here to turn your existing Spring Boot app into an MCP server — you're 3 steps away. You don't rewrite your code — you expose it.

Step 1: Add the MCP Server dependency

Swap in (or add) the Spring AI MCP Server starter. This gives your app a /mcp endpoint that speaks JSON-RPC 2.0 over Streamable HTTP — the wire protocol MCP uses under the hood.

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

spring.ai.mcp.server.name=my-mcp-server
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.protocol=STREAMABLE

That's the entire infrastructure change. No custom controllers, no manual JSON-RPC handling.

Step 2: Annotate your methods with @Tool

Take any existing Spring bean method and add @Tool + @ToolParam. This is what makes your logic discoverable by any MCP client.

@Component
public class PricingCalculatorTool {

    @Tool(description = "Calculate the total cost for a unicorn rental")
    public String calculatePrice(
            @ToolParam(description = "Name of the rental package") String packageName,
            @ToolParam(description = "Price per unit") int pricePerUnit,
            @ToolParam(description = "Number of hours or days") int duration,
            @ToolParam(description = "Include optional insurance") boolean includeInsurance) {
        // your existing business logic — unchanged
    }
}

Already have service classes with business logic? Just add the annotations. The method signatures become the tool's input schema — MCP clients see parameter names, types, and descriptions automatically.

Step 3: Register tools with a ToolCallbackProvider

Tell Spring AI which beans to expose over MCP:

@Configuration
public class McpServerConfig {

    @Bean
    public ToolCallbackProvider toolCallbackProvider(DateTimeTool dateTimeTool,
                                                     PricingCalculatorTool pricingCalculatorTool,
                                                     BookingTool bookingTool) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(dateTimeTool, pricingCalculatorTool, bookingTool)
                .build();
    }
}

Done. Spring Boot auto-configures the MCP endpoint. Any MCP client can now connect, discover your tools, and call them.

What happens under the hood

MCP uses JSON-RPC 2.0 as its wire format — every message is a JSON object with method, params, and id:

The session is stateful — the server returns an Mcp-Session-Id header on initialize,

... View full README on GitHub