Skip to content

mcp-annotated-java-sdk

Spring-free annotation layer for building lightweight MCP (Model Context Protocol) servers in plain Java.

🎯 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 server with just 1 line of code
  • 🎉 Low Boilerplate - No need to write repetitive low-level MCP SDK registration code
  • 👏 Generated JSON Schema - Derive tool schemas from annotated Java signatures and metadata
  • 🎯 Focus on Logic - Concentrate on core business logic
  • 🧩 Compile-Time Binding Generation - Annotation processing creates deterministic MCP component providers
  • 🔌 Spring AI-Friendly Configuration - Familiar configuration shape for teams that may also use Spring AI
  • 📦 Type-Aware - Leverage 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:

  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

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.
  • Required YAML — instructions must be non-blank; when mode is STREAMABLE, the streamable transport section must be present and complete.

📖 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.