modelcontextprotocol/java-sdk: the MCP Java SDK for servers and clients

What the MCP Java SDK solves, and who it is for

The Model Context Protocol defines how an AI model reaches external tools and data through a standardized interface. That interface is a wire contract, not a library, so every language community has to implement it. This repository is the Java implementation, maintained in collaboration with Spring AI, and it targets two audiences at once: teams writing an MCP server that exposes their own tools, and teams writing an MCP client that connects to someone else's server.

The README frames the goal plainly: a reference implementation of the MCP specification that is "pragmatic", "interoperable" and "pluggable". That word choice matters. This is not a framework that hides the protocol from you. If you want your business logic annotated and auto-wired, the README points you at Spring AI MCP instead, which extends this SDK with Spring Boot starters. The SDK itself assumes you are willing to assemble a server or client from parts.

Architecture: a core module, pluggable JSON, and two transports

The repository layout tells most of the story. mcp-core holds the protocol logic. mcp-json-jackson2 and mcp-json-jackson3 ship Jackson as the default JSON binding, but behind an SDK abstraction in the package io.modelcontextprotocol.json. The README states the reason directly: Jackson is widely adopted, has a mature annotation model, and is familiar to the team. Alternatives can be plugged in, which is the point of putting an interface where a dependency would normally be hardcoded.

The programming model supports both synchronous and asynchronous communication patterns, including cancellation and streaming, while the README says it stays simple for blocking use cases. Observability is listed as a first-class design area rather than an afterthought: logging plus integration points for metrics and tracing. Transport is split between client transport (consuming someone else's MCP server) and server transport (exposing your own endpoint, with authorization).

The honest reading of this architecture is that the SDK made three opinionated choices and left escape hatches for all three. Jackson is a default, not a requirement. The async model coexists with blocking calls. The transports are separate concerns rather than one monolithic server type. That is a reasonable posture for a specification implementation, though it does mean more wiring for you than a starter would demand.

Installing the MCP Java SDK and connecting a first client

The prerequisite is stated in the README badge: Java 17 or later. The artifact lives on Maven Central under the group io.modelcontextprotocol.sdk, and the README links a BOM at the quickstart dependencies page. Building from source uses the Maven wrapper, and the README notes tests need Docker and npx pre-installed:

./mvnw clean install -DskipTests

That command compiles and installs the modules locally without running the suite. If you do want the tests, the README gives `./mvnw test` and warns that Docker and npx must already be on the machine, because the suite spins up real transports rather than mocking them.

For a dependency declaration, the README points at the BOM rather than printing a version, so the exact coordinates and current version should be read from the quickstart page. The repository also carries mcp-bom/ as a top-level module, which is the artifact that aligns versions across the SDK modules.

If you want to verify your own server against the protocol, the README documents the conformance path. Start the servlet module, then drive it with the conformance CLI:

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

The README states the server suite passes 40 of 40 checks. The client suite is weaker: 3 of 4 scenarios and 9 of 10 checks. Auth, run through the Spring HTTP client, is 12 of 14 scenarios fully passing at 98.9 percent of checks. Those numbers come from the repository's own VALIDATION_RESULTS.md, and the README is not hiding the gaps.

Where the SDK is the wrong tool

The conformance table is the clearest limitation. The client suite does not fully pass. The auth suite does not fully pass either. If your use case depends on OAuth 2.0 flows against an MCP server, the README's own numbers say some scenarios are not fully green, and the auth validation runs through the Spring HTTP client rather than the JDK HTTP client. That is a real constraint, not a documentation gap you can read past.

The second limitation is structural. The README's design section concedes that "the Java ecosystem is powerful but fragmented" and that choices were grounded in "team familiarity". That is an honest admission that the SDK is not the only valid design. If your stack centers on a different JSON library or a different async runtime, the pluggable abstraction is there, but you are the one writing the adapter.

The third case is simply scope. If you are not implementing MCP, this SDK does nothing for you. It is not a general AI client library, and it is not a replacement for Spring AI if what you actually want is Boot auto-configuration and annotation-based method handling. The README routes that audience to the Spring AI MCP documentation explicitly.

Spring AI MCP versus the raw SDK

The real alternative here is not another protocol implementation, it is the layer above. Spring AI MCP extends this SDK with Spring Boot integration, providing both client and server starters, annotation-based method handling, and OAuth 2.0 plus API key security support. The README also points to Spring Initializr for bootstrapping.

The difference in approach is not cosmetic. With the raw SDK you construct and configure your server or client, choose a transport, and wire JSON yourself. With the Spring AI starters, that assembly is replaced by Boot auto-configuration and annotations, and security is handled by a dedicated module. The trade-off runs both ways: the starters pull in the Spring dependency graph and assume Spring is already your framework, while the raw SDK keeps you on plain Java 17 with Jackson as the only default binding.

A team already on Spring Boot should probably start with the starters and drop down to the SDK only where they need control. A team on Quarkus, Micronaut, or plain Java has no reason to take the Spring path at all.

Versioning, migration and the MIT licence

The repository carries both MIGRATION-1.0.md and MIGRATION-2.0.md at the top level, alongside VERSIONING.md, DEPENDENCY_POLICY.md, CHANGELOG.md and ROADMAP.md. That set of files is a signal in itself: the project has already shipped one breaking major transition and documents the second. The recent releases listed are v2.0.1, v1.1.4 and v0.18.4, all dated 2026-08-19, which means three release lines are being published rather than only the newest. If you are on a 1.x line, the existence of a maintained 1.1.4 alongside 2.0.1 matters for planning.

The last push to the repository was on 2026-09-09, so the project is not dormant. It is also not archived. Those are the only maintenance facts available here; the README does not publish a support window or a deprecation schedule for the older lines, so anyone staying on 1.x is doing so without a stated end date.

The licence is MIT, per the README badge and the LICENSE file. That is permissive and short, which means the usual obligations are attribution and preserving the notice. It says nothing about the MCP specification itself, patents, or the terms of any server you connect to, so treat the licence as covering this code only. Nothing here is legal advice.

Editorial conclusion

Adopt it if you are building an MCP server or client in Java and want the reference implementation rather than a framework wrapper, and if Java 17+ is already your baseline. Skip it if you want Spring Boot auto-configuration out of the box, or if you are not actually implementing MCP and only need a general-purpose SDK. Before committing, read MIGRATION-2.0.md, check the conformance-tests/VALIDATION_RESULTS.md file for the client and auth suites, and confirm which mcp-json-jackson module matches your Jackson major version.

Frequently asked questions

Official sources

1. License: MIT
2. modelcontextprotocol/java-sdk on GitHub
3. Project website
4. README
5. Releases