Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ For comprehensive guides and SDK API documentation
- [Java MCP Server](https://modelcontextprotocol.github.io/java-sdk/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.
The [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
The [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html) - provides comprehensive OAuth 2.0 and API key-based security support for Model Context Protocol implementations in Spring AI.
[Spring AI MCP](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) extends the MCP Java SDK with Spring Boot integration, providing both [client](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [server](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) starters.
The [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) - provides annotation-based method handling for MCP servers and clients in Java.
The [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html) - 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](https://start.spring.io).

## Development
Expand Down Expand Up @@ -139,21 +139,21 @@ MCP supports both clients (applications consuming MCP servers) and servers (appl

#### Client Transport in the SDK

* **SDK Choice**: JDK HttpClient (Java 11+) as the default client, with optional Spring WebClient support
* **SDK Choice**: JDK HttpClient (Java 11+) as the default client

* **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies. Spring WebClient support is available for Spring-based projects.
* **Why**: The JDK HttpClient is built-in, portable, and supports streaming responses. This keeps the default lightweight with no extra dependencies.

* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. A Spring module provides WebClient integration.
* **How we expose it**: MCP Client APIs are transport-agnostic. The core module ships with JDK HttpClient transport. Spring WebClient-based transport is available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.

* **How it fits the SDK**: This ensures all applications can talk to MCP servers out of the box, while allowing richer integration in Spring and other environments.

#### Server Transport in the SDK

* **SDK Choice**: Jakarta Servlet implementation in core, with optional Spring WebFlux and Spring WebMVC providers
* **SDK Choice**: Jakarta Servlet implementation in core

* **Why**: Servlet is the most widely deployed Java server API. WebFlux and WebMVC cover a significant part of the Spring community. Together these provide reach across blocking and non-blocking models.
* **Why**: Servlet is the most widely deployed Java server API, providing broad reach across blocking and non-blocking models without additional dependencies.

* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring modules extend support for WebFlux and WebMVC.
* **How we expose it**: Server APIs are transport-agnostic. Core includes Servlet support. Spring WebFlux and WebMVC server transports are available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+.

* **How it fits the SDK**: This allows developers to expose MCP servers in the most common Java environments today, while enabling other transport implementations such as Netty, Vert.x, or Helidon.

Expand All @@ -176,9 +176,10 @@ The SDK is organized into modules to separate concerns and allow adopters to bri
* `mcp-json-jackson3` – Jackson 3 implementation of JSON binding
* `mcp` – Convenience bundle (core + Jackson 3)
* `mcp-test` – Shared testing utilities
* `mcp-spring` – Spring integrations (WebClient, WebFlux, WebMVC)

For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use `mcp-spring` for deeper framework integration.
Spring integrations (WebClient, WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`).

For example, a minimal adopter may depend only on `mcp` (core + Jackson), while a Spring-based application can use the Spring AI `mcp-spring-webflux` or `mcp-spring-webmvc` artifacts for deeper framework integration.

Additionally, `mcp-test` contains integration tests for `mcp-core`.
`mcp-core` needs a JSON implementation to run full integration tests.
Expand Down
24 changes: 12 additions & 12 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
# Security Policy

Thank you for helping us keep the SDKs and systems they interact with secure.
Thank you for helping keep the Model Context Protocol and its ecosystem secure.

## Reporting Security Issues

This SDK is maintained by [Anthropic](https://www.anthropic.com/) as part of the Model
Context Protocol project.
If you discover a security vulnerability in this repository, please report it through
the [GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
for this repository.

The security of our systems and user data is Anthropic’s top priority. We appreciate the
work of security researchers acting in good faith in identifying and reporting potential
vulnerabilities.
Please **do not** report security vulnerabilities through public GitHub issues, discussions,
or pull requests.

Our security program is managed on HackerOne and we ask that any validated vulnerability
in this functionality be reported through their
[submission form](https://hackerone.com/anthropic-vdp/reports/new?type=team&report_type=vulnerability).
## What to Include

## Vulnerability Disclosure Program
To help us triage and respond quickly, please include:

Our Vulnerability Program Guidelines are defined on our
[HackerOne program page](https://hackerone.com/anthropic-vdp).
- A description of the vulnerability
- Steps to reproduce the issue
- The potential impact
- Any suggested fixes (optional)
2 changes: 1 addition & 1 deletion docs/blog/index.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
# Blog
# News
53 changes: 34 additions & 19 deletions docs/client.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@ The MCP Client is a key component in the Model Context Protocol (MCP) architectu
!!! tip
The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO, SSE, and Streamable HTTP client transport implementations without requiring external web frameworks.

Spring-specific transport implementations are available as an **optional** dependency `io.modelcontextprotocol.sdk:mcp-spring-webflux` for [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) users.
The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.

The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.

Expand Down Expand Up @@ -135,26 +136,20 @@ The client provides both synchronous and asynchronous APIs for flexibility in di

The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.

=== "STDIO"
### STDIO

Creates transport for process-based communication using stdin/stdout:
Creates transport for process-based communication using stdin/stdout:

```java
ServerParameters params = ServerParameters.builder("npx")
.args("-y", "@modelcontextprotocol/server-everything", "dir")
.build();
McpTransport transport = new StdioClientTransport(params);
```

=== "SSE (HttpClient)"

Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:
```java
ServerParameters params = ServerParameters.builder("npx")
.args("-y", "@modelcontextprotocol/server-everything", "dir")
.build();
McpTransport transport = new StdioClientTransport(params);
```

```java
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
```
### Streamable HTTP

=== "Streamable HTTP"
=== "Streamable HttpClient"

Creates a Streamable HTTP client transport for efficient bidirectional communication. Included in the core `mcp` module:

Expand All @@ -172,16 +167,36 @@ The transport layer handles the communication between MCP clients and servers, p
- Custom HTTP request customization
- Multiple protocol version negotiation

=== "SSE (WebFlux)"
=== "Streamable WebClient (external)"

Creates Streamable HTTP WebClient-based client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):

Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency:
```java
McpTransport transport = WebFluxSseClientTransport
.builder(WebClient.builder().baseUrl("http://your-mcp-server"))
.build();
```

### SSE HTTP (Legacy)

=== "SSE HttpClient"

Creates a framework-agnostic (pure Java API) SSE client transport. Included in the core `mcp` module:

```java
McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
```
=== "SSE WebClient (external)"

Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):

```java
WebClient.Builder webClientBuilder = WebClient.builder()
.baseUrl("http://your-mcp-server");
McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
```


## Client Capabilities

The client can be configured with various capabilities:
Expand Down
57 changes: 5 additions & 52 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Overview
title: Index
description: Introduction to the Model Context Protocol (MCP) Java SDK
---

Expand Down Expand Up @@ -27,7 +27,7 @@ enables standardized integration between AI models and tools.
- Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
- Servlet-based SSE server transport for HTTP SSE Server streaming
- [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http) transport for efficient bidirectional communication (client and server)
- Optional Spring-based transports (convenience if using Spring Framework):
- Optional Spring-based transports (available in [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+, no longer part of this SDK):
- WebFlux SSE client and server transports for reactive HTTP streaming
- WebFlux Streamable HTTP server transport
- WebMVC SSE server transport for servlet-based HTTP streaming
Expand All @@ -41,56 +41,9 @@ enables standardized integration between AI models and tools.
!!! tip
The core `io.modelcontextprotocol.sdk:mcp` module provides default STDIO, SSE, and Streamable HTTP client and server transport implementations without requiring external web frameworks.

Spring-specific transports are available as optional dependencies for convenience when using the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) and [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html).
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-security.html).

## Architecture

The SDK follows a layered architecture with clear separation of concerns:

![MCP Stack Architecture](images/mcp-stack.svg)

- **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
- **Session Layer (McpSession)**: Manages communication patterns and state.
- **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
- StdioTransport (stdin/stdout) in the core module
- HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
- Streamable HTTP transports for efficient bidirectional communication

The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
It implements the client-side of the protocol.

![Java MCP Client Architecture](images/java-mcp-client-architecture.jpg)

The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
It implements the server-side of the protocol.

![Java MCP Server Architecture](images/java-mcp-server-architecture.jpg)

Key Interactions:

- **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
- **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
- **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.

## Module Structure

The SDK is organized into modules to separate concerns and allow adopters to bring in only what they need:

| Module | Artifact ID | Purpose |
|--------|------------|---------|
| `mcp-bom` | `mcp-bom` | Bill of Materials for dependency management |
| `mcp-core` | `mcp-core` | Core reference implementation (STDIO, JDK HttpClient, Servlet, Streamable HTTP) |
| `mcp-json-jackson2` | `mcp-json-jackson2` | Jackson 2.x JSON serialization implementation |
| `mcp-json-jackson3` | `mcp-json-jackson3` | Jackson 3.x JSON serialization implementation |
| `mcp` | `mcp` | Convenience bundle (`mcp-core` + `mcp-json-jackson3`) |
| `mcp-test` | `mcp-test` | Shared testing utilities and integration tests |
| `mcp-spring-webflux` | `mcp-spring-webflux` | Spring WebFlux integration (SSE and Streamable HTTP) |
| `mcp-spring-webmvc` | `mcp-spring-webmvc` | Spring WebMVC integration (SSE and Streamable HTTP) |

!!! tip
A minimal adopter may depend only on `mcp` (core + Jackson 3), while a Spring-based application can add `mcp-spring-webflux` or `mcp-spring-webmvc` for deeper framework integration.
Spring-specific transports (WebFlux, WebMVC) are now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ and are no longer shipped by this SDK.
Use the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) from Spring AI.
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-security.html).

## Next Steps

Expand Down
Loading