Skip to content

MCP Java SDK

The Java SDK for the Model Context Protocol (MCP), the open protocol that connects AI applications to tools and data. Use it to build MCP clients and MCP servers in Java 17 or later, with a synchronous or an asynchronous API.

The SDK implements two generations of the protocol, side by side in the same module:

  • Modern, for the stateless 2026-07-28 specification, where every request stands alone.
  • Legacy, for the 2025-11-25 specification and earlier revisions, where client and server keep a session.

The names are the specification's own, and legacy does not mean deprecated here: the SDK supports both. See Modern or Legacy? to choose between them.

Features

What each implementation supports:

Feature Modern Legacy
Tools: discovery, calls, structured output Yes Yes
Resources and URI templates Yes Yes
Prompts Yes Yes
Completions for argument values Yes Yes
Elicitation: asking the user for input Yes, as a multi round-trip request (form and URL) Yes, as a request from the server
Sampling Server only Yes
Roots Server only Yes
Progress notifications Yes Yes
Logging No (deprecated by the revision) Yes
Change notifications Yes, with subscriptions/listen Yes, over the session
Finding out what a server supports server/discover initialize handshake
Caching hints on results Yes No
Custom HTTP headers for tool arguments (SEP-2243) Yes No

Both implementations share the following:

  • Sync and async APIs. Choose blocking calls or Project Reactor types.
  • Transports without a web framework. STDIO, and Streamable HTTP on the JDK HttpClient (client) and the Servlet API (server). The legacy implementation also has the deprecated SSE transport.
  • Pluggable JSON serialization. Jackson 3.x by default, or Jackson 2.x.
  • Security hooks. Pluggable authorization hooks, and opt-in DNS rebinding protection with Host/Origin header validation (see HTTP Transport Security).

Spring applications

Spring WebFlux and WebMVC transports for the legacy client and server are part of Spring AI 2.0+ and are not shipped by this SDK. Use the MCP Client Boot Starter and the MCP Server Boot Starter from Spring AI. For the modern client and server, Spring AI 2.1+ provides Boot starters and Spring transports; see MCP Client Boot Starter and MCP 2026-07-28 Servers. Also consider the MCP Annotations and MCP Security.

Getting Started

Add the mcp module, which bundles the core SDK with Jackson 3.x JSON serialization:

<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
</dependency>

The Quickstart covers versions, the BOM, Gradle, and the other modules.

Next Steps

  • Overview


    Understand the architecture, and choose between modern and legacy.

    Overview

  • 🚀 Quickstart


    Get started with dependencies and BOM configuration.

    Quickstart

  • MCP Client (Modern)


    Call stateless servers of the 2026-07-28 revision.

    Client

  • MCP Server (Modern)


    Build stateless servers for the 2026-07-28 revision.

    Server

  • MCP Client (Legacy)


    Create and configure clients for servers of the 2025-11-25 revision and earlier.

    Client

  • MCP Server (Legacy)


    Implement and configure servers for the 2025-11-25 revision and earlier.

    Server