Skip to content

Commit 6a28ebb

Browse files
authored
Document the modern client and restructure the docs (#1329)
Add a guide for the 2026-07-28 client (docs/client-modern.md) and bring the rest of the documentation in line with an SDK that has a classic and a modern client and server. - Navigation groups the guides into Classic and Modern. - Overview, index and quickstart are rewritten to cover both: a "Classic or Modern?" comparison, a feature table, and a first client call for each. - The classic architecture diagrams are redrawn as SVG, with matching modern ones added. - The modern client and server are no longer described as a preview. - CHANGELOG gains an entry for the modern client. Rename Classic to Legacy and add sync and async tabs to the docs Follow the terms of the MCP specification, which names the handshake-based revisions "legacy" and the per-request ones "modern". - Classic is renamed to Legacy in the navigation, the guides and the diagrams. Modern now comes first everywhere. - The SSE transport is labelled "Deprecated", as in the specification. - The modern client and server guides show each example in a Sync and an Async tab. - "Calling the Server" in the modern client guide explains the two steps of a call, in place of the "Spec" and "Terminal" columns. - Spring AI links point to the 2.1.0-SNAPSHOT reference. Update the docs for Spring AI 2.1 modern support - Spring AI 2.1+ integrates the modern client and server; both modern guides gain a "Spring" section and drop it from "Not Yet Supported". - Legacy server guide: spec links point to the 2025-11-25 revision. - Documentation development page: project structure matches the folder. Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
1 parent 9142ebe commit 6a28ebb

16 files changed

Lines changed: 2074 additions & 589 deletions

‎CHANGELOG.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,17 @@ Versioning follows [Semantic Versioning](https://semver.org/); see
1919

2020
## Unreleased (2.2.0)
2121

22-
- Preview of a stateless server for the **2026-07-28** MCP specification revision, in
22+
- A stateless server for the **2026-07-28** MCP specification revision, in
2323
`io.modelcontextprotocol.modern`, with Servlet (Streamable HTTP) and STDIO transports. It supports
2424
`server/discover`, multi round-trip requests with sealed `requestState`, `subscriptions/listen`, caching
2525
hints, required client capabilities and SEP-2243 `Mcp-Param` header validation. The API may change in minor
2626
releases until 3.0. See [MCP Server (2026-07-28)](docs/server-modern.md).
27+
- A client for the **2026-07-28** MCP specification revision, in
28+
`io.modelcontextprotocol.modern.client`, with Streamable HTTP (JDK `HttpClient`) and STDIO transports. It
29+
needs no `initialize` handshake and supports multi round-trip requests with form and URL elicitation,
30+
progress, `subscriptions/listen`, `server/discover` and SEP-2243 `Mcp-Param` headers. Sampling, roots and
31+
logging are not supported. The API may change in minor releases until 3.0. See
32+
[MCP Client (2026-07-28)](docs/client-modern.md).
2733
- Add `McpTransportContext.putAll(Map)`, returning a context that combines an
2834
existing context with additional entries, which take precedence.
2935
- `McpTransportContext` no longer compares contexts by their contents in

‎docs/client-modern.md‎

Lines changed: 751 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/client.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,13 @@ The MCP Client is a key component in the Model Context Protocol (MCP) architectu
1919
!!! tip
2020
The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO, SSE, and Streamable HTTP client transport implementations without requiring external web frameworks.
2121

22-
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.
23-
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.
22+
The Spring-specific WebFlux transport (`mcp-spring-webflux`) is now part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`) and is no longer shipped by this SDK.
23+
See the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) documentation for Spring-based client setup.
24+
25+
!!! note "2026-07-28 specification"
26+
This page covers the legacy client, which implements the 2025-11-25 specification and earlier revisions.
27+
A client for the stateless 2026-07-28 revision is also available; see
28+
[MCP Client (2026-07-28)](client-modern.md).
2429

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

@@ -168,15 +173,15 @@ McpTransport transport = new StdioClientTransport(params, McpJsonDefaults.getMap
168173

169174
=== "Streamable WebClient (external)"
170175

171-
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`):
176+
Creates Streamable HTTP WebClient-based client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
172177

173178
```java
174179
McpTransport transport = WebFluxSseClientTransport
175180
.builder(WebClient.builder().baseUrl("http://your-mcp-server"))
176181
.build();
177182
```
178183

179-
### SSE HTTP (Legacy)
184+
### SSE HTTP (Deprecated)
180185

181186
=== "SSE HttpClient"
182187

@@ -187,7 +192,7 @@ McpTransport transport = new StdioClientTransport(params, McpJsonDefaults.getMap
187192
```
188193
=== "SSE WebClient (external)"
189194

190-
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`):
195+
Creates WebFlux-based SSE client transport. Requires the `mcp-spring-webflux` dependency from [Spring AI](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ (group `org.springframework.ai`):
191196

192197
```java
193198
WebClient.Builder webClientBuilder = WebClient.builder()

‎docs/development.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,14 +51,17 @@ The built site will be output to the `site/` directory.
5151

5252
```
5353
docs/
54-
├── index.md # Overview page
54+
├── index.md # Home page
55+
├── overview.md # Architecture and modules
5556
├── quickstart.md # Quickstart guide
56-
├── client.md # MCP Client documentation
57-
├── server.md # MCP Server documentation
58-
├── contributing.md # Contributing guide
57+
├── client-modern.md # MCP Client, modern (2026-07-28)
58+
├── server-modern.md # MCP Server, modern (2026-07-28)
59+
├── client.md # MCP Client, legacy (2025-11-25 and earlier)
60+
├── server.md # MCP Server, legacy (2025-11-25 and earlier)
61+
├── contribute.md # Contributing guide
5962
├── development.md # This page
60-
├── images/ # Images and diagrams
61-
└── stylesheets/ # Custom CSS
63+
├── blog/ # Blog posts
64+
└── images/ # Images and diagrams
6265
mkdocs.yml # MkDocs configuration
6366
```
6467

Lines changed: 78 additions & 0 deletions
Loading
Lines changed: 121 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)