MCP Java SDK

The MCP Java SDK provides implementations for both MCP Clients and MCP Servers, enabling standardized integration between AI models and tools.

Key capabilities include:

• Protocol Support: Version compatibility negotiation, Tools (discovery, execution, schema validation), Resources (URI templates), Roots management, Prompts handling, Sampling, Elicitation (user input requests), Completions (argument autocompletion), Progress notifications, and Structured Logging.
• Programming Paradigms: Supports both Synchronous and Asynchronous programming.
• Extensibility: Pluggable JSON serialization (Jackson 2.x/3.x) and pluggable authorization hooks for server security.
• Security: Includes DNS rebinding protection via Host/Origin header validation.

The SDK uses a layered architecture to separate protocol logic from communication methods:

• Client/Server Layer (McpClient/McpServer): Handles high-level protocol operations using McpSession for both synchronous and asynchronous operations.
• Session Layer (McpSession): Manages the state and communication patterns between the client and server.
• Transport Layer (McpTransport): Responsible for JSON-RPC message serialization and deserialization. Supported transports include:
  • StdioTransport (via mcp-core)
  • HTTP SSE transports (via dedicated transport modules like Java HttpClient or Servlet)
  • Streamable HTTP transports for bidirectional communication
  • Spring WebFlux and Spring WebMVC transports (provided via Spring AI 2.0+)

The client is a Spring Boot application that uses conditional configuration to route scenarios:

• DefaultConfiguration: Activated for all scenarios except auth/pre-registration. It uses the OAuth2 Authorization Code flow with dynamic client registration via McpClientOAuth2Configurer.
• PreRegistrationConfiguration: Activated only for auth/pre-registration. It uses the Client Credentials flow with pre-registered credentials provided via the MCP_CONFORMANCE_CONTEXT environment variable.

Key Dependencies:

• Spring Boot 4.0 with Spring Security OAuth2 Client
• Spring AI MCP Client (spring-ai-starter-mcp-client)
• mcp-client-security (community library for MCP-specific OAuth2 integration)

To generate the static HTML files for deployment, run the build command. The output will be located in the site/ directory.

mkdocs build

To build the executable JAR for the JDK HTTP Client conformance test client, use the Maven wrapper from the root of the repository. This creates an executable JAR in the target/ directory of the module.

cd conformance-tests/client-jdk-http-client
../../mvnw clean package -DskipTests

To validate an MCP Java Server implementation, you can run the active conformance suite against a running server instance. This requires starting the server via Maven and then using the @modelcontextprotocol/conformance CLI tool to execute tests against the server's URL.

Note: The server must be running on a reachable URL (e.g., http://localhost:8080/mcp) before starting the test command.

# Start server
./mvnw compile -pl conformance-tests/server-servlet -am exec:java

# Run tests (in another terminal)
npx @modelcontextprotocol/conformance server --url http://localhost:8080/mcp --suite active

To validate an MCP Java Client implementation, build the client JAR using Maven and then use the @modelcontextprotocol/conformance CLI to run specific scenarios against the client's command execution.

Note: You must iterate through the desired scenarios (e.g., initialize, tools_call, elicitation-sep1034-client-defaults, sse-retry) using the client command.

# Build
cd conformance-tests/client-jdk-http-client
../../mvnw clean package -DskipTests

# Run all scenarios
for scenario in initialize tools_call elicitation-sep1034-client-defaults sse-retry; do
  npx @modelcontextprotocol/conformance client \
    --command "java -jar target/client-jdk-http-client-1.1.0-SNAPSHOT.jar" \
    --scenario $scenario
done

In version 1.0.0, the mcp aggregator module defaults to Jackson 3.

If your project requires Jackson 2 (com.fasterxml.jackson 2.x), you must stop using the mcp aggregator and instead depend on the individual modules mcp-core and mcp-json-jackson2.

If you are ready to use Jackson 3, you can continue using the mcp aggregator.

<!-- For Jackson 2 users -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-core</artifactId>
    <version>1.0.0-RC3</version>
</dependency>
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp-json-jackson2</artifactId>
    <version>1.0.0-RC3</version>
</dependency>

<!-- For Jackson 3 users -->
<dependency>
    <groupId>io.modelcontextprotocol.sdk</groupId>
    <artifactId>mcp</artifactId>
    <version>1.0.0-RC3</version>
</dependency>