MCP Annotated Java SDK

Build lightweight Model Context Protocol servers in plain Java with annotations, generated schemas, and no Spring runtime.

Get Started View on GitHub

Spring-free

Run MCP servers in plain Java applications, CLI tools, embedded processes, and small services.

Annotation-driven

Define tools, resources, prompts, and completions with concise, type-aware Java annotations.

Compile-time generation

Generate deterministic component bindings and JSON schemas during compilation.

Multiple transports

Serve local clients over STDIO or expose production integrations over Streamable HTTP.

What is MCP?

Model Context Protocol (MCP) is a standardized protocol for building servers that expose data and functionality to LLM applications. Similar to Web API, but specifically designed for LLM interactions.

Why this SDK?

MCP helps you build agents and complex workflows on top of LLMs. The official MCP Java SDK is the foundation layer, while Spring AI MCP is the standard entry point for Spring applications. This SDK exists for the plain Java path: CLI tools, embedded servers, local automation, and small service processes that benefit from annotations but do not need a Spring runtime.

Positioning

Project	Best fit	Role
Official MCP Java SDK	Library authors and low-level protocol integration	Foundation
Spring AI MCP	Spring Boot / Spring Framework applications	Spring ecosystem standard
mcp-annotated-java-sdk	Plain Java, CLI, embedded, and lightweight MCP servers	Spring-free annotation layer

Rule of thumb: Spring AI for Spring apps; mcp-annotated-java-sdk for lightweight Java MCP servers without Spring.

Key Advantages

No Spring Framework required pure Java, lightweight and fast
Instant MCP server start a server with one line of code
Low boilerplate avoid repetitive low-level MCP SDK registration code
Generated JSON Schema derive tool schemas from annotated Java signatures and metadata
Compile-time binding generation produce deterministic MCP component providers
Type-aware use Java signatures and compile-time checks for safer MCP components

Comparison

Feature	Official MCP Java SDK	Spring AI MCP	This SDK
Primary audience	Low-level Java integrations	Spring applications	Plain Java MCP servers
Spring required	No	Yes, for Spring integration	No
Component model	Programmatic registration	Spring beans and annotations	Plain classes and annotations
JSON Schema	Manual or app-provided	Generated by Spring AI	Generated by annotation processor
Startup model	You assemble the server	Spring Boot auto-configuration	`McpApplication.run(...)`
Best use case	Maximum control	Enterprise Spring apps	CLI, embedded, local tools, small services

Roadmap Focus

Keep close compatibility with the official MCP Java SDK.
Make plain Java MCP servers faster to write, test, and ship.
Improve compile-time validation, generated bindings, schema support, and examples.
Avoid competing with Spring AI on Boot auto-configuration, WebMVC/WebFlux integration, enterprise security, or observability.

Use Cases

This SDK is especially suitable for the following scenarios:

Rapid Prototyping - Quickly validate MCP concepts and functionality
CLI and Local Tools - STDIO-based tools for editors, agents, and desktop workflows
Embedded Servers - MCP capabilities embedded into existing plain Java processes
Local Automation - Small servers that expose scripts, files, or internal workflows
Teaching Demonstrations - Easy to understand and learn MCP protocol concepts

Supported Server Modes

Mode	Description	Use Case
STDIO	Standard input/output communication	CLI tools, local development
STREAMABLE	HTTP streaming	Web applications, recommended for production

Runtime notes

ASYNC vs SYNC type: ASYNC selects the async MCP server API; your annotated methods stay blocking Java wrapped in Mono.fromCallable(...). See Getting Started Runtime model.
Singleton components one instance per component class, shared across concurrent requests; keep handlers stateless or thread-safe.
Explicit YAML core fields and applicable nested settings must be specified explicitly in mcp-server.yml; instructions must be non-blank, capabilities.subscribe-resource is required only when resource support is enabled, and the streamable section must be present and complete only when mode is STREAMABLE. Defaults apply only when building a configuration programmatically via ServerConfiguration.builder().

Getting Started

Want to get started quickly? Check out the Getting Started Guide to learn how to build your first MCP server in 5 minutes.

Quick Links

Getting Started Guide - Build your first MCP server
Core Components - Resources, Tools, Prompts, and Completions
GitHub Repository - Source code and examples
Examples - Real-world examples

Edit page

Last updated: Aug 8, 2026

Next
Getting Started