MCP Java SDK: The Official Java Implementation of the Model Context Protocol
The official Java SDK for Model Context Protocol servers and clients. Maintained in collaboration with Spring AI
At a glance
- What is it?
- The official Java SDK for the Model Context Protocol gives Java applications a standard way to act as MCP clients or servers. It ships with Jackson as the default JSON layer, supports synchronous and asynchronous patterns, and is maintained alongside Spring AI. The trade-off is that parts of the client and auth conformance suites are still not fully passing.
- Who is it for?
- Adopt the MCP Java SDK if you need a spec-aligned MCP client or server in Java 17+ and want Jackson as a pluggable default rather than a hard dependency. Do not adopt it if you need a fully green conformance record today: the client suite reports 3 of 4 scenarios and 9 of 10 checks, and the Spring auth suite reports 12 of 14 scenarios fully passing.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Java, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Java gap the MCP specification left open
The Model Context Protocol defines how AI models reach tools and data through a standardized interface. The specification describes the protocol; it does not hand you a Java implementation. That leaves every Java team writing its own JSON-RPC framing, its own transport handling, and its own client and server lifecycle code before it can connect anything to an MCP endpoint. The java-sdk repository exists to close that gap: it is described as a set of projects providing Java SDK integration for MCP, supporting both synchronous and asynchronous communication. The audience is Java developers building either side of the connection. On the client side, that means an application that wants to consume tools exposed by an MCP server. On the server side, that means a team exposing its own Java services as MCP endpoints for AI clients to call. The repository topics (java, mcp-client, mcp-server) match that split. It is not a framework for building AI models, and it is not a protocol specification. It is the reference implementation of the specification in Java, maintained in collaboration with Spring AI, with the stated goal of being pragmatic, interoperable, pluggable, and grounded in team familiarity.
Jackson behind an abstraction, and why that choice matters
The SDK's design notes are unusually explicit about serialization. JSON mapping between JSON and Java types is handled by Jackson, but Jackson sits behind an SDK abstraction in the io.modelcontextprotocol.json package inside mcp-core. Jackson ships as the default implementation in a module named mcp-json-jackson3, and the design notes state that alternatives can be plugged in. This is a deliberate hedge. The Java ecosystem has multiple JSON libraries with strong communities, and the team chose not to force one on every project. If your application already standardizes on a different mapper, the abstraction is the seam where you swap it. The cost is an extra layer between your code and the wire format. When serialization behaves unexpectedly, you are debugging through an interface rather than calling Jackson directly. The benefit is that a JSON library choice does not become a migration project. The design notes frame this as making the SDK pragmatic and pluggable rather than prescriptive, and the phrase they use is that the goal is not to prescribe the one true way. Whether that abstraction holds up for every MCP message shape is something the documentation does not spell out, so treat the pluggability as a documented intent and verify it against your own message types.
Client and server transports, and the four design decisions
The SDK's architecture section lists four areas where the JDK provides limited or no support and where the team had to make choices: JSON serialization, the programming model, observability, and remote clients and servers. The programming model has to support asynchronous processing, cancellation, and streaming while staying simple for blocking use cases. That is the hardest of the four, because MCP interactions are long-lived and cancellable, and Java's blocking and reactive idioms pull in different directions. The SDK's answer is to support both synchronous and asynchronous communication patterns rather than picking one. The fourth area covers both directions of transport: consuming MCP servers as a client, and exposing MCP endpoints as a server with authorization. The repository layout reflects this. There is a client-jdk-http-client conformance module and a client-spring-http-client conformance module, which tells you the SDK ships more than one HTTP client path, with the Spring HTTP client path being the one exercised for auth conformance. Observability is named as a design area, but the README excerpt does not describe the specific logging, metrics, or tracing integration, so anyone who needs to wire MCP calls into an existing telemetry stack should read the observability documentation directly rather than assume an integration exists.
Getting it running: Maven coordinates and the build commands
The README points to a BOM for dependency management under the quickstart section, and the Maven Central badge references the artifact io.modelcontextprotocol.sdk:mcp. The Java version badge states Java 17 or later. To build from source, the README gives a single command: ./mvnw clean install -DskipTests. Running the test suite requires two external tools pre-installed, Docker and npx, and the command is ./mvnw test. The Docker and npx requirement is worth noting before you put this in CI: a plain JVM build agent will not run the tests as they are written. The SDK is validated against the MCP conformance test suite at version 0.1.15, and the README provides separate commands for each suite. Server conformance compiles the server-servlet module and runs it with exec:java, then invokes npx @modelcontextprotocol/conformance server against http://localhost:8080/mcp with the active suite. Client conformance packages the client-jdk-http-client module and loops four scenarios (initialize, tools_call, elicitation-sep1034-client-defaults, sse-retry) through npx @modelcontextprotocol/conformance client. Auth conformance packages the client-spring-http-client module and runs npx @modelcontextprotocol/conformance@0.1.15 client with --spec-version 2025-11-25 and the auth suite. That pinned spec version is a concrete signal of which protocol revision the auth path targets.
The conformance numbers are the honest part of the README
The README publishes a conformance table rather than a claim of full compliance. Server conformance reports 40 of 40 passed, which is a clean result. Client conformance reports 3 of 4 scenarios and 9 of 10 checks passed. Auth conformance, run through the Spring HTTP client, reports 12 of 14 scenarios fully passing at 98.9 percent of checks. Those are not failures to hide; they are published with instructions to reproduce them locally. But they do define the boundary of what the SDK currently guarantees. If your application depends on the specific client scenario that is not passing, or on one of the two auth scenarios that are not fully passing, you are working ahead of the validated surface. The validation results file at conformance-tests/VALIDATION_RESULTS.md is where the detail lives, and it is the first thing to read before assuming a given MCP feature works end to end. The suite is pinned at 0.1.15, so conformance against a newer suite version is not established by this table. The design notes also acknowledge that multiple valid approaches exist in the Java ecosystem, which is a reasonable stance for a reference implementation but means the SDK does not try to be the only answer.
Where the SDK is the wrong tool, and what to use instead
If you are building a Spring Boot application and want MCP support with minimal wiring, the SDK is the layer underneath, not the top layer. Spring AI extends the MCP Java SDK with Spring Boot integration, providing both client and server starters, plus MCP Annotations for annotation-based method handling and MCP Security for OAuth 2.0 and API key support. The difference in approach is concrete: with the raw SDK you assemble transports, clients, and servers yourself and follow the client and server documentation pages; with the Spring AI starters you get auto-configuration and annotation-driven method exposure, and the auth conformance run in this repository is executed through the Spring HTTP client path. If your stack is not Spring, the starters are not for you, and the SDK's pluggable JSON layer and transport modules are the reason it can still fit. A second case where the SDK is the wrong choice: if you need a fully passing conformance record across client and auth scenarios today, this repository does not claim one. A third: if you are not on Java 17 or later, the SDK is out of scope, and the README states the requirement plainly rather than offering a backport.
Maintenance, versioning, and the MIT licence
The repository is not archived, was last pushed on 2026-09-09, and shows three maintained release lines: v2.0.1, v1.1.4, and v0.18.4, all dated 2026-08-19. Three parallel lines is a real maintenance consideration. A 2.x, a 1.x, and a 0.x line all receiving releases on the same day means the project is carrying compatibility branches, and it means you need to decide which line you are on before you write code, because the conformance modules in the README are built against 2.0.1-SNAPSHOT artifacts. The project is maintained in collaboration with Spring AI and lists a three-person team in the README, which is a small group for a specification-tracking library. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code, though the README does not discuss how the licence interacts with the separate Spring AI project or with the conformance suite, which lives in a different repository. Nothing here is legal advice; if licence terms matter to your organisation, read the MIT text and the Spring AI project's own terms rather than relying on a badge.
Editorial conclusion
Adopt the MCP Java SDK if you need a spec-aligned MCP client or server in Java 17+ and want Jackson as a pluggable default rather than a hard dependency. Do not adopt it if you need a fully green conformance record today: the client suite reports 3 of 4 scenarios and 9 of 10 checks, and the Spring auth suite reports 12 of 14 scenarios fully passing. Before committing, run the conformance commands from the README against your own transport and confirm which MCP spec version your target servers negotiate.
Community notes