Skip to content
Back to search

java-sdk

The official Java SDK for Model Context Protocol servers and clients. Maintained in collaboration with Spring AI

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/modelcontextprotocol/java-sdk with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/modelcontextprotocol/java-sdk'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/modelcontextprotocol--java-sdk/badge.svg)](/listings/modelcontextprotocol--java-sdk)

HTML

<a href="/listings/modelcontextprotocol--java-sdk"><img src="/api/listings/modelcontextprotocol--java-sdk/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 237 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Java SDK
  2. [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/MIT)
  3. [![Build Status](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/publish-snapshot.yml/badge.svg)](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/publish-snapshot.yml)
  4. [![Maven Central](https://img.shields.io/maven-central/v/io.modelcontextprotocol.sdk/mcp.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/io.modelcontextprotocol.sdk/mcp)
  5. [![Java Version](https://img.shields.io/badge/Java-17%2B-orange)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
  6. A set of projects that provide Java SDK integration for the [Model Context Protocol](https://modelcontextprotocol.io/docs/concepts/architecture).
  7. This SDK enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns.
  8. ## 📚 Reference Documentation
  9. #### MCP Java SDK documentation
  10. For comprehensive guides and SDK API documentation
  11. - [Features](https://modelcontextprotocol.github.io/java-sdk/#features) - Overview the features provided by the Java MCP SDK
  12. - [Architecture](https://modelcontextprotocol.github.io/java-sdk/#architecture) - Java MCP SDK architecture overview.
  13. - [Java Dependencies / BOM](https://java.sdk.modelcontextprotocol.io/latest/quickstart/#dependencies) - Java dependencies and BOM.
  14. - [Java MCP Client](https://java.sdk.modelcontextprotocol.io/latest/client/) - Learn how to use the MCP client to interact with MCP servers.
  15. - [Java MCP Server](https://java.sdk.modelcontextprotocol.io/latest/server/) - Learn how to implement and configure a MCP servers.
  16. #### Spring AI MCP documentation
  17. [Spring AI MCP](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) starters.
  18. The [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
  19. The [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
  20. Bootstrap your AI applications with MCP support using [Spring Initializer](https://start.spring.io).
  21. ## Development
  22. ### Building from Source
  23. ```bash
  24. ./mvnw clean install -DskipTests
  25. ```
  26. ### Running Tests
  27. To run the tests you have to pre-install `Docker` and `npx`.
  28. ```bash
  29. ./mvnw test
  30. ```
  31. ### Conformance Tests
  32. The SDK is validated against the [MCP conformance test suite](https://github.com/modelcontextprotocol/conformance) at 0.1.15 version.
  33. Full details and instructions are in [`conformance-tests/VALIDATION_RESULTS.md`](conformance-tests/VALIDATION_RESULTS.md).
  34. **Latest results:**
  35. | Suite | Result |
  36. |---------------|-----------------------------------------------------|
  37. | Server | ✅ 40/40 passed (100%) |
  38. | Client | 🟡 3/4 scenarios, 9/10 checks passed |
  39. | Auth (Spring) | 🟡 12/14 scenarios fully passing (98.9% checks) |
  40. To run the conformance tests locally you need `npx` installed.
  41. ```bash
  42. # Server conformance
  43. ./mvnw compile -pl conformance-tests/server-servlet -am exec:java
  44. npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active
  45. # Client conformance
  46. ./mvnw clean package -DskipTests -pl conformance-tests/client-jdk-http-client -am
  47. for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
  48. npx @modelcontextprotocol/conformance client \
  49. --command "java -jar conformance-tests/client-jdk-http-client/target/client-jdk-http-client-*-SNAPSHOT.jar" \
  50. --scenario $scenario
  51. done
  52. # Auth conformance (Spring HTTP Client)
  53. ./mvnw clean package -DskipTests -pl conformance-tests/client-spring-http-client -am
  54. npx @modelcontextprotocol/conformance@0.1.15 client \
  55. --spec-version 2025-11-25 \
  56. --command "java -jar conformance-tests/client-spring-http-client/target/client-spring-http-client-*-SNAPSHOT.jar" \
  57. --suite auth
  58. ```
  59. ## Contributing
  60. Contributions are welcome!
  61. Please follow the [Contributing Guidelines](CONTRIBUTING.md).
  62. ## Team
  63. - Christian Tzolov
  64. - Dariusz Jędrzejczyk
  65. - Daniel Garnier-Moiroux
  66. ## Links
  67. - [GitHub Repository](https://github.com/modelcontextprotocol/java-sdk)
  68. - [Issue Tracker](https://github.com/modelcontextprotocol/java-sdk/issues)
  69. - [CI/CD](https://github.com/modelcontextprotocol/java-sdk/actions)
  70. ## Architecture and Design Decisions
  71. ### Introduction
  72. 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.
  73. Our goal is not to prescribe "the one true way," but to provide a reference implementation of the MCP specification that is:
  74. * **Pragmatic** – makes developers productive quickly
  75. * **Interoperable** – aligns with widely used libraries and practices
  76. * **Pluggable** – allows alternatives where projects prefer different stacks
  77. * **Grounded in team familiarity** – we chose technologies the team can be productive with today, while remaining open to community contributions that broaden the SDK
  78. ### Key Choices and Considerations
  79. The SDK had to make decisions in the following areas:
  80. 1. **JSON serialization** – mapping between JSON and Java types
  81. 2. **Programming model** – supporting asynchronous processing, cancellation, and streaming while staying simple for blocking use cases
  82. 3. **Observability** – logging and enabling integration with metrics/tracing
  83. 4. **Remote clients and servers** – supporting both consuming MCP servers (client transport) and exposing MCP endpoints (server transport with authorization)
  84. The following sections explain what we chose, why it made sense, and how the choices align with the SDK's goals.
  85. ### 1. JSON Serialization
  86. * **SDK Choice**: Jackson for JSON serialization and deserialization, behind an SDK abstraction (package `io.modelcontextprotocol.json` in `mcp-core`)
  87. * **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.
  88. * **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.
  89. * **How it fits the SDK**: This offers a pragmatic default while keeping flexibility for projects that prefer different JSON libraries.
  90. ### 2. Programming Model
  91. * **SDK Choice**: Reactive Streams for public APIs, with Project Reactor as the internal implementation and a synchronous facade for blocking use cases
  92. * **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:
  93. * Multiple in-flight requests and responses
  94. * Notifications that do not expect a reply
  95. * STDIO transports for inter-process communication using pipes
  96. * Streaming transports such as Server-Sent Events and Streamable HTTP
  97. These requirements call for a programming model more powerful than single-result futures like `CompletableFuture`.
  98. * **Reactive Streams: the Community Standard**
  99. 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.
  100. * **Reactive Streams Implementation**
  101. 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.
  102. 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.
  103. * **Synchronous Facade in the SDK**
  104. Not all MCP use cases require streaming pipelines. Many scenarios are as simple as "send a request and block until I get the result."
  105. 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.
  106. * **How it fits the SDK**: This design balances scalability, approachability, and future evolution such as Virtual Threads and Structured Concurrency in upcoming JDKs.
  107. ### 3. Observability
  108. * **SDK Choice**: SLF4J for logging; Reactor Context for observability propagation
  109. * **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.
  110. * **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.
  111. * **How it fits the SDK**: This provides reliable logging by default and seamless integration with Micrometer, OpenTelemetry, or similar systems for metrics and tracing.
  112. ### 4. Remote MCP Clients and Servers
  113. MCP supports both clients (applications consuming MCP servers) and servers (applications exposing MCP endpoints). The SDK provides support for both sides.
  114. #### Client Transport in the SDK
  115. * **SDK Choice**: JDK HttpClient (Java 11+) as the default client
  116. * **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies.
  117. * **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. Spring WebClient-based transport is available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
  118. * **How it fits the SDK**: This ensures all applications can talk to MCP servers out of the box, while allowing richer integration in Spring and other environments.
  119. #### Server Transport in the SDK
  120. * **SDK Choice**: Jakarta Servlet implementation in core
  121. * **Why**: Servlet is the most widely deployed Java server API, providing broad reach across blocking and non-blocking models without additional dependencies.
  122. * **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring WebFlux and WebMVC server transports are available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.
  123. * **How it fits the SDK**: This allows developers to expose MCP servers in the most common Java environments today, while enabling other transport implementations such as Netty, Vert.x, or Helidon.
  124. #### Authorization in the SDK
  125. * **SDK Choice**: Pluggable authorization hooks for MCP servers; no built-in implementation
  126. * **Why**: MCP servers must restrict access to authenticated and authorized clients. Authorization needs differ across environments such as Spring Security, MicroProfile JWT, or custom solutions. Providing hooks avoids lock-in and leverages proven libraries.
  127. * **How we expose it**: Authorization is integrated into the server transport layer. The SDK does not include its own authorization system.
  128. * **How it fits the SDK**: This keeps server-side security ecosystem-neutral, while ensuring applications can plug in their preferred authorization strategy.
  129. ### Project Structure of the SDK
  130. The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:
  131. * `mcp-bom` – Dependency versions
  132. * `mcp-core` – Reference implementation (STDIO, JDK HttpClient, Servlet), JSON binding interface definitions
  133. * `mcp-json-jackson2` – Jackson 2 implementation of JSON binding
  134. * `mcp-json-jackson3` – Jackson 3 implementation of JSON binding
  135. * `mcp` – Convenience bundle (core + Jackson 3)
  136. * `mcp-test` – Shared testing utilities
  137. Spring integrations (WebClient, WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`).
  138. For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use the Spring AI `mcp-spring-webflux` or `mcp-spring-webmvc` artifacts for deeper framework integration.
  139. Additionally, `mcp-test` contains integration tests for `mcp-core`.
  140. `mcp-core` needs a JSON implementation to run full integration tests.
  141. Implementations such as `mcp-json-jackson3`, depend on `mcp-core`, and therefore cannot be imported in `mcp-core` for tests.
  142. Instead, all integration tests that need a JSON implementation are now in `mcp-test`, and use `jackson3` by default.
  143. A `jackson2` maven profile allows to run integration tests with Jackson 2, like so:
  144. ```bash
  145. ./mvnw -pl mcp-test -am -Pjackson2 test
  146. ```
  147. ### Future Directions
  148. The SDK is designed to evolve with the Java ecosystem. Areas we are actively watching include:
  149. Concurrency in the JDK – Virtual Threads and Structured Concurrency may simplify the synchronous API story
  150. ## License
  151. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.