MCP Java SDK

A set of projects that provide Java SDK integration for the Model Context Protocol. This SDK enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns.

📚 Reference Documentation

MCP Java SDK documentation

For comprehensive guides and SDK API documentation

• Features - Overview the features provided by the Java MCP SDK
• Architecture - Java MCP SDK architecture overview.
• Java Dependencies / BOM - Java dependencies and BOM.
• Java MCP Client - Learn how to use the MCP client to interact with MCP servers.
• Java MCP Server - Learn how to implement and configure a MCP servers.

Spring AI MCP documentation

Spring AI MCP extends the MCP Java SDK with Spring Boot integration, providing both client and server starters. The MCP Annotations - provides annotation-based method handling for MCP servers and clients in Java. The MCP Security - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI. Bootstrap your AI applications with MCP support using Spring Initializer.

Development

Building from Source

./mvnw clean install -DskipTests

Running Tests

To run the tests you have to pre-install Docker and npx.

./mvnw test

Conformance Tests

The SDK is validated against the MCP conformance test suite at 0.1.15 version. Full details and instructions are in conformance-tests/VALIDATION_RESULTS.md.

Latest results:

To run the conformance tests locally you need npx installed.

# Server conformance
./mvnw compile -pl conformance-tests/server-servlet -am exec:java
npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active

# Client conformance
./mvnw clean package -DskipTests -pl conformance-tests/client-jdk-http-client -am
for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
  npx @modelcontextprotocol/conformance client \
    --command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-2.0.1-SNAPSHOT.jar" \
    --scenario $scenario
done

# Auth conformance (Spring HTTP Client)
./mvnw clean package -DskipTests -pl conformance-tests/client-spring-http-client -am
npx @modelcontextprotocol/conformance@0.1.15 client \
  --spec-version 2025-11-25 \
  --command "java -jar conformance-tests/client-spring-http-client/target/client-spring-http-client-2.0.1-SNAPSHOT.jar" \
  --suite auth

Contributing

Contributions are welcome! Please follow the Contributing Guidelines.

Team

• Christian Tzolov
• Dariusz Jędrzejczyk
• Daniel Garnier-Moiroux

Links

• GitHub Repository
• Issue Tracker
• CI/CD

Architecture and Design Decisions

Introduction

Building a general-purpose MCP Java SDK requires making technology decisions in areas where the JDK provides limited or no support. The Java ecosystem is powerful but fragmented: multiple valid approaches exist, each with strong communities. Our goal is not to prescribe "the one true way," but to provide a reference implementation of the MCP specification that is:

• Pragmatic – makes developers productive quickly
• Interoperable – aligns with widely used libraries and practices
• Pluggable – allows alternatives where projects prefer different stacks
• Grounded in team familiarity – we chose technologies the team can be productive with today, while remaining open to community contributions that broaden the SDK

Key Choices and Considerations

The SDK had to make decisions in the following areas:

1. JSON serialization – mapping between JSON and Java types

2. Programming model – supporting asynchronous processing, cancellation, and streaming while staying simple for blocking use cases

3. Observability – logging and enabling integration with metrics/tracing

4. Remote clients and servers – supporting both consuming MCP servers (client transport) and exposing MCP endpoints (server transport with authorization)

The following sections explain what we chose, why it made sense, and how the choices align with the SDK's goals.

1. JSON Serialization

• SDK Choice: Jackson for JSON serialization and deserialization, behind an SDK abstraction (package io.modelcontextprotocol.json in mcp-core)

• Why: Jackson is widely adopted across the Java ecosystem, provides strong performance and a mature annotation model, and is familiar to the SDK team and many potential contributors.

• How we expose it: Public APIs use a bundled abstraction. Jackson is shipped as the default implementation (mcp-json-jackson3), but alternatives can be plugged in.

• How it fits the SDK: This offers a pragmatic default while keeping flexibility for projects that prefer different JSON libraries.

2. Programming Model

• SDK Choice: Reactive Streams for public APIs, with Project Reactor as the internal implementation and a synchronous facade for blocking use cases

• Why: MCP builds on JSON-RPC's asynchronous nature and defines a bidirectional protocol on top of it, enabling asynchronous and streaming interactions. MCP explicitly supports:

  • Multiple in-flight requests and responses
  • Notifications that do not expect a reply
  • STDIO transports for inter-process communication using pipes
  • Streaming transports such as Server-Sent Events and Streamable HTTP

  These requirements call for a programming model more powerful than single-result futures like CompletableFuture.

  • Reactive Streams: the Community Standard

    Reactive Streams is a small Java specification that standardizes asynchronous stream processing with backpressure. It defines four minimal interfaces (Publisher, Subscriber, Subscription, and Processor). These interfaces are widely recognized as the standard contract for async, non-blocking pipelines in Java.

  • Reactive Streams Implementation

    The SDK uses Project Reactor as its implementation of the Reactive Streams specification. Reactor is mature, widely adopted, provides rich operators, and integrates well with observability through context propagation. Team familiarity also allowed us to deliver a solid foundation quickly. We plan to convert the public API to only expose Reactive Streams interfaces. By defining the public API in terms of Reactive Streams interfaces and using Reactor internally, the SDK stays standards-based while benefiting from a practical, production-ready implementation.

  • Synchronous Facade in the SDK

    Not all MCP use cases require streaming pipelines. Many scenarios are as simple as "send a request and block until I get the result." To support this, the SDK provides a synchronous facade layered on top of the reactive core. Developers can stay in a blocking model when it's enough, while still having access to asynchronous streaming when needed.

• How it fits the SDK: This design balances scalability, approachability, and future evolution such as Virtual Threads and Structured Concurrency in upcoming JDKs.

3. Observability

• SDK Choice: SLF4J for logging; Reactor Context for observability propagation

• Why: SLF4J is the de facto logging facade in Java, with broad compatibility. Reactor Context enables propagation of observability data such as correlation IDs and tracing state across async boundaries. This ensures interoperability with modern observability frameworks.

• How we expose it: Public APIs log through SLF4J only, with no backend included. Observability metadata flows through Reactor pipelines. The SDK itself does not ship metrics or tracing implementations.

• How it fits the SDK: This provides reliab