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.
-
Quickstart
Get started with dependencies and BOM configuration.
-
MCP Client (Modern)
Call stateless servers of the 2026-07-28 revision.
-
MCP Server (Modern)
Build stateless servers for the 2026-07-28 revision.
-
MCP Client (Legacy)
Create and configure clients for servers of the 2025-11-25 revision and earlier.
-
MCP Server (Legacy)
Implement and configure servers for the 2025-11-25 revision and earlier.