java-sdk

# MCP Java SDK [](https://opensource.org/license/MIT) [](https://github.com/modelcontextprotocol/java-sdk/actions/workflows/publish-snapshot.yml) [](https://central.sonatype.com/artifact/io.modelcontextprotocol.sdk/mcp) [](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) A set of projects that provide Java SDK integration for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture). This SDK enables Java applications to interact with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns. ## 📚 Reference Documentation #### MCP Java SDK documentation For comprehensive guides and SDK API documentation - [Features](https://modelcontextprotocol.io/sdk/java/mcp-overview#features) - Overview the features provided by the Java MCP SDK - [Architecture](https://modelcontextprotocol.io/sdk/java/mcp-overview#architecture) - Java MCP SDK architecture overview. - [Java Dependencies / BOM](https://modelcontextprotocol.io/sdk/java/mcp-overview#dependencies) - Java dependencies and BOM. - [Java MCP Client](https://modelcontextprotocol.io/sdk/java/mcp-client) - Learn how to use the MCP client to interact with MCP servers. - [Java MCP Server](https://modelcontextprotocol.io/sdk/java/mcp-server) - Learn how to implement and configure a MCP servers. #### Spring AI MCP documentation [Spring AI MCP](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) starters. Bootstrap your AI applications with MCP support using [Spring Initializer](https://start.spring.io). ## Development ### Building from Source ```bash ./mvnw clean install -DskipTests ``` ### Running Tests To run the tests you have to pre-install `Docker` and `npx`. ```bash ./mvnw test ``` ## Contributing Contributions are welcome! Please follow the [Contributing Guidelines](CONTRIBUTING.md). ## Team - Christian Tzolov - Dariusz Jędrzejczyk - Daniel Garnier-Moiroux ## Links - [GitHub Repository](https://github.com/modelcontextprotocol/java-sdk) - [Issue Tracker](https://github.com/modelcontextprotocol/java-sdk/issues) - [CI/CD](https://github.com/modelcontextprotocol/java-sdk/actions) ## Architecture and Design Decisions ### Introduction 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. Our goal is not to prescribe "the one true way," but to provide a reference implementation of the MCP specification that is: * **Pragmatic** – makes developers productive quickly * **Interoperable** – aligns with widely used libraries and practices * **Pluggable** – allows alternatives where projects prefer different stacks * **Grounded in team familiarity** – we chose technologies the team can be productive with today, while remaining open to community contributions that broaden the SDK ### Key Choices and Considerations The SDK had to make decisions in the following areas: 1. **JSON serialization** – mapping between JSON and Java types 2. **Programming model** – supporting asynchronous processing, cancellation, and streaming while staying simple for blocking use cases 3. **Observability** – logging and enabling integration with metrics/tracing 4. **Remote clients and servers** – supporting both consuming MCP servers (client transport) and exposing MCP endpoints (server transport with authorization) The following sections explain what we chose, why it made sense, and how the choices align with the SDK's goals. ### 1. JSON Serialization * **SDK Choice**: Jackson for JSON serialization and deserialization, behind an SDK abstraction (`mcp-json`) * **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. * **How we expose it**: Public APIs use a zero-dependency abstraction (`mcp-json`). Jackson is shipped as the default implementation (`mcp-jackson2`), but alternatives can be plugged in. * **How it fits the SDK**: This offers a pragmatic default while keeping flexibility for projects that prefer different JSON libraries. ### 2. Programming Model * **SDK Choice**: Reactive Streams for public APIs,