java-sdk: The Official Java SDK for Model Context Protocol

Introduction

The java-sdk is the official Java SDK designed to facilitate interaction with Model Context Protocol (MCP) servers and clients. This SDK empowers Java applications to seamlessly integrate with AI models and tools through a standardized interface, supporting both synchronous and asynchronous communication patterns. Maintained in collaboration with Spring AI, the java-sdk offers comprehensive support for building modern AI-driven applications, including Spring Boot integration for both client and server functionalities.

Installation

To get started with the java-sdk, you can build it directly from the source code. Stable releases are also available via Maven Central.

Building from Source

./mvnw clean install -DskipTests

Running Tests

To run the tests, ensure you have Docker and npx pre-installed on your system.

./mvnw test

For stable releases, you can find the java-sdk on Maven Central.

Examples

The java-sdk provides extensive capabilities for both consuming and exposing Model Context Protocol endpoints. For detailed examples and comprehensive guides on using the SDK, refer to the official documentation:

MCP Java Client: Learn how to use the MCP client to interact with MCP servers.
- Documentation Link
MCP Java Server: Discover how to implement and configure MCP servers.
- Documentation Link

Additionally, for Spring-based applications, the SDK extends its functionality with Spring Boot integration, allowing for quick bootstrapping of AI applications:

Spring AI MCP Client Boot Starter:
- Documentation Link
Spring AI MCP Server Boot Starter:
- Documentation Link

These resources provide practical examples and detailed instructions to help you integrate MCP into your Java and Spring AI projects.

Why Use the java-sdk?

The java-sdk is built with a strong focus on pragmatism, interoperability, and pluggability, making it a robust choice for developing AI-powered applications in Java. Its design decisions address key challenges in the Java ecosystem, ensuring developers can be productive quickly while maintaining flexibility.

Key aspects that make the java-sdk a compelling choice include:

Pragmatic Design: The SDK aims to make developers productive quickly by providing sensible defaults and clear abstractions.
Interoperability: It aligns with widely adopted libraries and practices in the Java ecosystem, such as Jackson for JSON serialization and SLF4J for logging.
Pluggability: The architecture allows for alternatives where projects prefer different stacks, for example, by offering pluggable JSON libraries, client/server transports, and authorization hooks.
Thoughtful Technology Choices:
- JSON Serialization: Uses Jackson as the default, widely adopted and performant, but provides an abstraction (mcp-json) for easy swapping.
- Programming Model: Leverages Reactive Streams with Project Reactor for asynchronous and streaming interactions, crucial for MCP's bidirectional protocol. A synchronous facade is also provided for simpler, blocking use cases.
- Observability: Integrates SLF4J for logging and Reactor Context for propagating observability data across asynchronous boundaries, ensuring compatibility with modern tracing and metrics frameworks.
- Remote Clients and Servers: Offers JDK HttpClient as the default client transport and Jakarta Servlet for server transport, with optional Spring WebClient, WebFlux, and WebMVC integrations for Spring-based projects. It also includes pluggable authorization hooks for server-side security.
Modular Structure: The SDK is organized into distinct modules, allowing users to include only the necessary components, promoting lightweight and efficient dependency management.