modelcontextprotocol / java-sdk

# MCP Java SDK
A set of projects that provide Java SDK integration for the Model Context Protocol. 
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 - Overview the features provided by the Java MCP SDK
- Architecture - Java MCP SDK architecture overview.
- Java Dependencies / BOM - Java dependencies and BOM.
- Java MCP Client - Learn how to use the MCP client to interact with MCP servers.
- Java MCP Server - Learn how to implement and configure a MCP servers.
#### Spring AI MCP documentation
Spring AI MCP extends the MCP Java SDK with Spring Boot integration, providing both client and server starters. 
The MCP Annotations - provides annotation-based method handling for MCP servers and clients in Java.
The MCP Security - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
Bootstrap your AI applications with MCP support using Spring Initializer.
## Development
### Building from Source
 [code] 
### Running Tests
To run the tests you have to pre-install `Docker` and `npx`.
 [code] 
### Conformance Tests
The SDK is validated against the MCP conformance test suite at 0.1.15 version.
Full details and instructions are in `conformance-tests/VALIDATION_RESULTS.md`.
**Latest results:**
| Suite | Result |
|---------------|-----------------------------------------------------|
| Server | ✅ 40/40 passed (100%) |
| Client | 🟡 3/4 scenarios, 9/10 checks passed |
| Auth (Spring) | 🟡 12/14 scenarios fully passing (98.9% checks) |
To run the conformance tests locally you need `npx` installed.
 [code] 
## Contributing
Contributions are welcome!
Please follow the Contributing Guidelines.
## Team
- Christian Tzolov
- Dariusz Jędrzejczyk
- Daniel Garnier-Moiroux
## Links
- GitHub Repository
- Issue Tracker
- CI/CD
## 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. **Programmi