java-sdk
The official Java SDK for Model Context Protocol servers and clients. Maintained in collaboration with Spring AI
claude mcp add --transport stdio modelcontextprotocol-java-sdk java -jar path/to/mcp-server.jar \ --env JAVA_OPTS="Optional Java runtime options" \ --env MCP_CONFIG="Path to MCP server configuration (if required)"
How to use
The MCP Java SDK provides a Java-based implementation for interacting with AI models and tools through the Model Context Protocol. It offers both client and server capabilities, with support for asynchronous, streaming, and bidirectional communication powered by Reactive Streams and Project Reactor. The SDK exposes a server component that can host MCP endpoints with authorization, making it suitable for integrating model tooling, tool wrappers, and conversational agents into Java applications. It also aligns with Spring Boot through the Spring AI MCP ecosystem, enabling annotation-based handling and security features for MCP endpoints. You can leverage the MCP client to connect to MCP servers, perform requests, receive responses, and handle streaming data as it arrives, all while benefiting from Java’s strong typing and ecosystem.
How to install
Prerequisites:
- Java 17+ JDK installed
- Maven or Maven Wrapper available
- Git installed
Step 1: Clone the repository
git clone https://github.com/modelcontextprotocol/java-sdk.git
cd java-sdk
Step 2: Build from source (skip tests if you just want the artifacts)
./mvnw clean install -DskipTests
Step 3: Run unit tests (requires Docker and npx if tests rely on those tools)
./mvnw test
Step 4: Use the SDK in your project
- If you are adding as a dependency, reference the Maven coordinates from the project’s BOM and dependencies as documented in the repository.
- For running a server example, ensure you have a valid Java runtime and invoke the server entry point as described in the server documentation (for example via a jar or module path).
Additional notes
Tips and common considerations:
- Java 17+ is recommended; ensure your environment matches the Java version used by the SDK.
- When running tests that require external tooling, you may need Docker and npx installed as indicated in the repository’s development notes.
- The SDK emphasizes Reactive Streams with Project Reactor; for blocking usage, you can leverage the provided synchronous facade.
- If you are extending the server with Spring Boot, explore the MCP server integration guides and annotations for endpoint handling and security configuration.
- Review the JSON serialization options (Jackson-based by default) and consider customizing the JSON layer if you have specific serialization needs.
