Skip to content
MCP Annotated Java SDK

MCP Annotated Java SDK

Build lightweight Model Context Protocol servers in plain Java with annotations, generated schemas, and no Spring runtime.
Get StartedView 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?

Section titled “🎯 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?

Section titled “✨ 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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Use Cases”

This SDK is especially suitable for the following scenarios:

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

Supported Server Modes

Section titled “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

Section titled “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

Section titled “📖 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

Section titled “🔗 Quick Links”