MCP Server using Spring Boot Java

A Model Context Protocol (MCP) server implementation built with Spring Boot and Java 21. This project demonstrates how to create an MCP server that provides comprehensive books management tools for AI assistants with an in-memory H2 database.

Features

• Implements MCP server functionality using Spring AI
• Exposes books management tools via MCP
• In-memory H2 database with JPA/Hibernate integration
• Synchronous communication mode
• Support for Standard I/O and Server-Sent Events transports
• Pre-loaded sample book data for immediate testing
• Complete CRUD operations for book management
• Advanced search and filtering capabilities

Technologies

• Java 21
• Spring Boot 3.5.3
• Spring AI (Model Context Protocol)
• Spring Data JPA
• H2 Database (In-Memory)
• Hibernate
• Bean Validation
• Maven

Getting Started

Prerequisites

• Java 21 or higher
• Maven

Installation

1. Clone the repository

git clone https://github.com/mishravivek-ms/SpringbootSampleMCPServer.git
cd SpringbootSampleMCPServer

2. Build the project

mvn clean package

3. Run the application

java -jar target/examplemcpserver-0.0.1-SNAPSHOT.jar

Alternatively, you can run it directly with Maven:

mvn spring-boot:run

Configuration

The MCP server is configured in application.yml:

• Server runs on port 8081
• Server name: examplemcpserver
• Synchronous communication mode
• Supports STDIO transport for terminal-based communication
• Exposes /mcp/sse and /mcp/sse/message endpoints for SSE communication
• H2 database console available at /h2-console

Database Configuration

H2 In-Memory Database

• URL: jdbc:h2:mem:testdb
• Username: sa
• Password: password
• Console Access: http://localhost:8081/h2-console
• Auto-initialization: 20+ sample books loaded on startup

Sample Data

The server automatically loads diverse sample books including:

• Classic Literature (To Kill a Mockingbird, 1984, Pride and Prejudice)
• Science Fiction (Dune, Foundation, Neuromancer)
• Fantasy (Lord of the Rings, Game of Thrones)
• Programming Books (Clean Code, Design Patterns, Effective Java)
• Non-Fiction (Sapiens, The Lean Startup)

Available Tools

The server exposes the following book management tools:

Core CRUD Operations

• add_book - Add a new book to the library
• remove_book - Remove a book by ID
• update_book - Update an existing book
• get_book_by_id - Get a specific book by ID
• get_all_books - Get all books in the library

Search and Query Tools

• search_books_by_name - Search books by name (partial match)
• search_books_by_author - Search books by author (partial match)
• get_books_by_year - Get books published in a specific year
• get_books_by_price_range - Get books within a price range

Analytics Tools

• get_library_stats - Get comprehensive library statistics

Additional Tools

• Mathematical operations: add, subtract, multiply, divide
• Date manipulation tools

🛠️ Tool Architecture & Extensibility

How Easy It Is to Add New LLM Functionality

One of the most powerful features of this MCP server is how incredibly simple it is to extend functionality for LLMs. The architecture demonstrates a clean, annotation-driven approach that requires minimal code to expose new capabilities to AI assistants.

Tool Implementation Examples

1. BookTool.java - Complex Business Logic Made Simple

package com.example.examplemcpserver.tools;

@Component
public class BookTool {
    
    @Autowired
    private BookService bookService;
    
    @Tool(name = "add_book", description = "Add a new book to the library")
    public String addBook(String bookName, String author, Integer yearOfPublishing, Double price) {
        // Full validation and business logic
        Book book = new Book(bookName.trim(), author.trim(), yearOfPublishing, BigDecimal.valueOf(price));
        Book savedBook = bookService.addBook(book);
        return String.format("Successfully added book: '%s' by %s...", savedBook.getBookName(), savedBook.getAuthor());
    }
    
    @Tool(name = "search_books_by_author", description = "Search books by author name")
    public String searchBooksByAuthor(String author) {
        // Complex database queries made available to LLMs with one annotation
        List<Book> books = bookService.findBooksByAuthorContaining(author);
        // ... formatting logic
    }
}

Key Features:

• Full Spring Integration: Dependency injection, transaction management, validation
• Rich Business Logic: Complex database operations exposed as simple tool calls
• Error Handling: Comprehensive validation and exception handling
• Type Safety: Strong typing with automatic parameter validation

2. MathTool.java - Simple Utilities in Seconds

package com.example.examplemcpserver.tools;

public class MathTool {
    
    @Tool(name = "add", description = "Adds two numbers")
    public int add(int a, int b) {
        return a + b;
    }
    
    @Tool(name = "divide", description = "Divides two numbers")
    public double divide(int a, int b) {
        if (b == 0) {
            throw new IllegalArgumentException("Division by zero is not allowed.");
        }
        return (double) a / b;
    }
}

Demonstrates:

• Zero Configuration: No annotations other than @Tool needed
• Automatic Type Conversion: LLM inputs automatically converted to method parameters
• Exception Handling: Java exceptions automatically handled by MCP framework

3. DateTool.java - Modern Java API Integration

package com.example.examplemcpserver.tools;

public class DateTool {
    
    @Tool(name = "addDays", description = "Adds days to the current date")
    public LocalDate addDays(int days) {
        return LocalDate.now().plusDays(days);
    }
    
    @Tool(name = "subtractDays", description = "Subtracts days from the current date")
    public LocalDate subtractDays(int days) {
        return LocalDate.now().minusDays(days);
    }
}

Shows:

• Modern Java APIs: Direct integration with Java 8+ time APIs
• Return Type Flexibility: Any serializable Java type can be returned
• Minimal Code: Maximum functionality with minimal implementation

Registration Made Simple

In ExamplemcpserverApplication.java, registering tools is as easy as:

import com.example.examplemcpserver.tools.BookTool;
import com.example.examplemcpserver.tools.MathTool;
import com.example.examplemcpserver.tools.DateTool;

@Bean
public ToolCallbackProvider mathTools() {
    return MethodToolCallbackProvider.builder()
            .toolObjects(new MathTool())  // ← Register any POJO
            .build();
}

@Bean  
public ToolCallbackProvider bookTools() {
    return MethodToolCallbackProvider.builder()
            .toolObjects(bookTool)        // ← Register Spring-managed beans
            .build();
}

🚀 Adding Your Own Tools - 3 Simple Steps

Want to add weather functionality? Here's how easy it is:

Step 1: Create the Tool Class

package com.example.examplemcpserver.tools;

@Component
public class WeatherTool {
    
    @Autowired
    private WeatherService weatherService;  // Your business logic
    
    @Tool(name = "get_current_weather", description = "Get current weather for a city")
    public String getCurrentWeather(String city) {
        return weatherService.getWeather(city);
    }
    
    @Tool(name = "get_forecast", description = "Get 5-day weather forecast")
    public List<WeatherData> getForecast(String city, int days) {
        return weatherService.getForecast(city, days);
    }
}

Step 2: Register in Main Application

import com.example.examplemcpserver.tools.WeatherTool;

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

Step 3: That's It! 🎉

Your weather tools are now available to all LLMs connected to your MCP server. AI assistants can now:

• Ask: "What's the weather in Seattle?"
• Request: "Give me a 5-day forecast for Tokyo"
• Command: "Compare weather between London and Paris"

💡 Why This Architecture Is Powerful

1. Zero Boilerplate: The @Tool annotation handles all MCP protocol complexities
2. Type Safety: Compile-time checking of parameters and return types
3. Spring Integration: Full access to dependency injection, AOP, transactions
4. Automatic Documentation: Tool descriptions become part of the MCP schema
5. Error Handling: Java exceptions automatically converted to MCP error responses
6. Flexibility: Support for simple POJOs or complex Spring-managed services

🎯 Real-World Extension Ideas

With this pattern, you could easily add:

• File Operations: @Tool methods for reading, writing, searching files
• Email Tools: Send emails, check inbox, manage contacts
• API Integrations: Weather, news, social media, payment processing
• Database Tools: Query different databases, generate reports
• System Tools: Monitor resources, manage processes, check logs
• AI/ML Tools: Image processing, text analysis, model inference

Each new capability requires only:

• One Java class with @Tool annotated methods
• One bean registration in the main application class

The MCP framework handles everything else - protocol communication, parameter validation, error handling, and making your tools available to AI assistants worldwide!

Testing with MCP Inspector

You can use the MCP Inspector client to test and interact with your MCP server:

Prerequisites

1. Install the MCP Inspector globally:

npm install -g @modelcontextprotocol/inspector

Connecting to the Server

1. Start the MCP server:

mvn spring-boot:run

2. In a new terminal, launch the MCP Inspector:

mcp-inspector

3. Connect to your server using the SSE transport:

   • Transport Type: SSE (Server-Sent Events)
   • URL: http://localhost:8081/mcp/sse
   • Server Name: examplemcpserver

4. Once connected, you'll see all available tools in the Inspector interface

Using the Inspector Interface

The MCP Inspector provides a user-friendly interface to:

• View Available Tools: Browse all 16 registered tools including book management, math, and date tools
• Inspect Tool Schemas: See parameter requirements and descriptions for each tool
• Execute Tools: Run tools with proper parameter validation
• View Responses: See formatted responses from tool executions
• Monitor Real-time: Watch for server notifications and updates

Example Tool Executions

Example Tool Executions

Get All Books

• Tool: get_all_books
• Parameters: None
• Description: Retrieves all books in the library with their details

Add a New Book

• Tool: add_book
• Parameters:
  • bookName: "Clean Architecture"
  • author: "Robert C. Martin"
  • yearOfPublishing: 2017
  • price: 47.99
• Description: Adds a new book to the library

Search Books by Author

• Tool: search_books_by_author
• Parameters:
  • author: "Martin"
• Description: Finds all books by authors containing "Martin"

Get Books by Price Range

• Tool: get_books_by_price_range
• Parameters:
  • minPrice: 10.0
  • maxPrice: 25.0
• Description: Retrieves books within the specified price range

Update an Existing Book

• Tool: update_book
• Parameters:
  • bookId: 1
  • bookName: "Updated Book Title"
  • author: "Updated Author"
  • yearOfPublishing: 2024
  • price: 29.99
• Description: Updates an existing book with new information

Remove a Book

• Tool: remove_book
• Parameters:
  • bookId: 1
• Description: Removes a book from the library by its ID

Get Library Statistics

• Tool: get_library_stats
• Parameters: None
• Description: Provides comprehensive statistics about the library

Advanced Testing

The Inspector also allows you to:

• Test Mathematical Operations: Use add, subtract, multiply, divide tools
• Explore Date Tools: Access various date manipulation functions
• Monitor Notifications: See real-time updates when tools or resources change
• Validate Parameters: Get immediate feedback on parameter requirements

The MCP Inspector provides a much more intuitive way to interact with your MCP server compared to raw HTTP requests.

Usage with AI Clients (Claude, ChatGPT, etc.)

🤖 The Power of AI Integration

This MCP server transforms your book management into a conversational AI experience. Instead of using traditional interfaces, you can simply talk to AI assistants like Claude, ChatGPT, or other MCP-compatible clients using natural language:

Example Conversations:

• "Add Clean Architecture by Robert Martin to my library"
• "Show me all books by authors with 'Martin' in their name"
• "What's the most expensive book in my collection?"
• "Find books published between 2010 and 2020 under $30"

Claude Desktop Integration

Configure this server in Claude Desktop by adding to your MCP configuration:

{
  "mcpServers": {
    "books-management-server": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-Dspring.main.web-application-type=none",
        "-Dlogging.pattern.console=",
        "-jar",
        "path/to/examplemcpserver-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Other MCP Clients

This server is compatible with any MCP-enabled client:

• Claude Desktop: Most popular choice with excellent MCP support
• Continue.dev: VS Code extension for AI-powered development
• Custom MCP Clients: Build your own using the MCP SDK
• Web Clients: Connect via SSE endpoints for browser-based interactions

🌟 Why This Is Powerful

1. Natural Language Interface: No need to remember specific API calls or commands
2. Context Awareness: AI understands your intent and chooses the right tools
3. Complex Queries: Combine multiple operations in a single conversation
4. Real-time Updates: Changes are immediately reflected in your database
5. Error Handling: AI provides helpful feedback when operations fail

🚀 Real-World AI Scenarios

Scenario 1: Library Discovery

You: "What programming books do I have?"
Claude: I'll search your library for programming books.
[Uses search_books_by_name with "programming" and related terms]
Claude: "You have 4 programming books: Clean Code ($45.99), Design Patterns ($54.99), Effective Java ($49.99), and Spring in Action ($52.99)."

Scenario 2: Smart Recommendations

You: "I liked Clean Code. What similar books do I have?"
Claude: Let me check for other books by Robert Martin or similar topics.
[Uses search_books_by_author("Robert") and analyzes your collection]
Claude: "You also have Clean Architecture by the same author, Robert C. Martin, published in 2017 for $47.99."

Scenario 3: Library Management

You: "Add the latest book on microservices architecture, priced around $40"
Claude: I'll add that book to your library.
[Uses add_book with the details provided]
Claude: "I've added 'Microservices Architecture' to your library. The book is now available in your collection."

Scenario 4: Analytics & Insights

You: "Give me a summary of my book collection"
Claude: Let me analyze your library statistics.
[Uses get_library_stats and get_all_books for detailed analysis]
Claude: "Your library contains 21 books spanning from 1813 to 2021, with prices ranging from $10.99 to $54.99. You have a great mix of classic literature, sci-fi, and technical books!"

Architecture

Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/example/examplemcpserver/
│   │       ├── entity/
│   │       │   └── Book.java
│   │       ├── repository/
│   │       │   └── BookRepository.java
│   │       ├── service/
│   │       │   └── BookService.java
│   │       ├── config/
│   │       │   └── DataInitializer.java
│   │       ├── exception/
│   │       │   └── GlobalExceptionHandler.java
│   │       ├── tools/
│   │       │   ├── BookTool.java
│   │       │   ├── MathTool.java
│   │       │   └── DateTool.java
│   │       └── ExamplemcpserverApplication.java
│   └── resources/
│       └── application.yml

Key Components

• Book Entity: JPA entity with validation annotations
• BookRepository: Spring Data JPA repository with custom queries
• BookService: Business logic layer with transaction management
• Tools Package: Contains all MCP tool implementations
  • BookTool: Book management operations (CRUD, search, analytics)
  • MathTool: Mathematical operations for LLM calculations
  • DateTool: Date manipulation utilities
• DataInitializer: Automatic sample data loading
• GlobalExceptionHandler: Centralized error handling

Development

Running in Development Mode

mvn spring-boot:run

Accessing H2 Console

Navigate to http://localhost:8081/h2-console with:

• JDBC URL: jdbc:h2:mem:testdb
• Username: sa
• Password: password

Adding New Tools

1. Create methods in appropriate tool classes in the tools package (e.g., BookTool.java, MathTool.java, DateTool.java)
2. Annotate with @Tool(name = "tool_name", description = "description")
3. Register the tool in ExamplemcpserverApplication.java
4. Import the tool class: import com.example.examplemcpserver.tools.YourToolClass;

Error Handling

The server includes comprehensive error handling:

• Input validation with detailed error messages
• Duplicate book detection
• Not found scenarios
• Database constraint violations
• Global exception handling with appropriate HTTP status codes

Monitoring and Logging

• SQL query logging enabled for debugging
• MCP protocol debugging enabled
• Console logging with structured format
• Health monitoring through Spring Boot Actuator (can be enabled)