java-mcp-server

Annotation-driven Model Context Protocol (MCP) server toolkit for Java 17+ and Spring Boot 3.

Add mcp-server-spring-boot to any Spring Boot web app and annotate methods with @McpTool or @McpResource — the rest is auto-configured.

Quick start

@Component
public class MyTools {

    @McpTool(name = "greet", description = "Say hello to someone")
    public String greet(
        @McpParam(value = "name", description = "Person's name") String name
    ) {
        return "Hello, " + name + "!";
    }

    @McpResource(uri = "config://app/{key}", description = "Read a config value")
    public String config(@McpParam("key") String key) {
        return System.getProperty(key, "(not set)");
    }
}

Start the app and call the MCP endpoint:

# Handshake
curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{}}'

# List tools
curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}'

# Call a tool
curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"3","method":"tools/call","params":{"name":"greet","arguments":{"name":"Alice"}}}'

# Read a resource
curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"4","method":"resources/read","params":{"uri":"config://app/java.version"}}'

Modules

Module	Description
mcp-core	Annotations (@McpTool, @McpResource, @McpParam) and JSON-RPC/tool models. No Spring dependency.
mcp-server-spring-boot	Spring Boot auto-configuration: scans beans, builds tool registry, exposes the /mcp endpoint.
mcp-server-sample	Runnable sample with SystemInfoTools (JVM info, env vars, system properties) and MathTools (add, divide, stats).

Annotations

@McpTool

Attribute	Required	Description
name	no	Tool name sent to clients. Defaults to the method name.
description	no	Human-readable description included in the tool manifest.

@McpResource

Attribute	Required	Description
uri	yes	URI or URI template ({variable}) identifying the resource.
name	no	Display name. Defaults to the method name.
description	no	Human-readable description.
mimeType	no	Content MIME type. Defaults to text/plain.

@McpParam

Attribute	Required	Description
value	yes	JSON parameter name.
description	no	Included in the JSON schema for the tool.
required	no	Whether the parameter is required. Default: true.

Adding to your project

<dependency>
    <groupId>com.ayushwing</groupId>
    <artifactId>mcp-server-spring-boot</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

The MCP endpoint defaults to /mcp. Override it in application.properties:

mcp.endpoint=/api/mcp

Running the sample

cd mcp-server-sample
mvn spring-boot:run
# Server starts on http://localhost:8090

MCP protocol version

This implementation targets MCP 2024-11-05 (JSON-RPC 2.0 over HTTP).

Building

mvn clean install -DskipTests