Skip to main content
GitHub • Maven

​
Overview

The MCP Annotations project provides annotation-based method handling for Model Context Protocol (MCP) servers in Java. It simplifies the creation and registration of MCP server methods through a clean, declarative approach using Java annotations.

​
Features

Annotation-based

Simplifies creation and registration of MCP methods

Sync & Async

Support for both synchronous and asynchronous operations

Stateful & Stateless

Full server exchange or lightweight transport context

Auto Schema Generation

Automatic JSON schema generation from method signatures

Dynamic Schemas

Handle dynamic schemas at runtime via CallToolRequest

Type Safe

Full Java type safety with comprehensive validation

​
Key Components

​
Server Annotations

Annotates methods that implement MCP tools with automatic JSON schema generation
Annotates methods that provide access to resources via URI templates
Annotates methods that generate prompt messages
Annotates methods that provide completion functionality for prompts or URI templates

​
Client Annotations

Handle logging message notifications from MCP servers
Handle sampling requests from MCP servers
Handle progress notifications for long-running operations
Handle elicitation requests to gather additional information from users

​
Quick Start

​
Installation

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>mcp-annotations</artifactId>
    <version>...</version>
</dependency>
And the Java MCP SDK: 
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>...</version>
</dependency>

​
Simple Tool Example

public class CalculatorToolProvider {

    @McpTool(name = "add", description = "Add two numbers together")
    public int add(
            @McpToolParam(description = "First number to add", required = true) int a,
            @McpToolParam(description = "Second number to add", required = true) int b) {
        return a + b;
    }

    @McpTool(name = "multiply", description = "Multiply two numbers")
    public double multiply(
            @McpToolParam(description = "First number", required = true) double x,
            @McpToolParam(description = "Second number", required = true) double y) {
        return x * y;
    }
}

​
Create MCP Server

List<SyncToolSpecification> toolSpecifications =
    new SyncMcpToolProvider(List.of(calculatorProvider)).getToolSpecifications();

McpSyncServer syncServer = McpServer.sync(transportProvider)
    .serverInfo("calculator-server", "1.0.0")
    .capabilities(ServerCapabilities.builder()
        .tools(true)
        .build())
    .tools(toolSpecifications)
    .build();

​
Spring AI MCP Integration

For a complete out-of-the-box experience with Spring Boot, Spring AI provides full MCP support with auto-configurations.

Getting Started with MCP

Official Spring AI MCP quick start guide

MCP Annotations Overview

Complete Spring AI MCP Annotations documentation

Server Annotations

Server-side annotation reference

MCP Annotations Example

Official Spring AI example project

​
Requirements

  • Java 17 or higher
  • Reactor Core (for async operations)
  • MCP Java SDK 0.13.0-SNAPSHOT or higher

​
Resources

GitHub Repository

View source code and contribute

Maven Central

Download releases and snapshots

​
License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
⌘I