Skip to content

Commit 38519ce

Browse files
committed
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. Signed-off-by: Christian Tzolov <christian.tzolov@broadcom.com>
1 parent 251ce0d commit 38519ce

11 files changed

Lines changed: 858 additions & 454 deletions

‎docs/client-modern.md‎

Lines changed: 302 additions & 124 deletions
Large diffs are not rendered by default.

‎docs/client.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,11 @@ 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.
2424

2525
!!! note "2026-07-28 specification"
26-
This page covers the classic client, which implements the 2025-11-25 specification and earlier revisions.
26+
This page covers the legacy client, which implements the 2025-11-25 specification and earlier revisions.
2727
A client for the stateless 2026-07-28 revision is also available; see
2828
[MCP Client (2026-07-28)](client-modern.md).
2929

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

174174
=== "Streamable WebClient (external)"
175175

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.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`):
177177

178178
```java
179179
McpTransport transport = WebFluxSseClientTransport
180180
.builder(WebClient.builder().baseUrl("http://your-mcp-server"))
181181
.build();
182182
```
183183

184-
### SSE HTTP (Legacy)
184+
### SSE HTTP (Deprecated)
185185

186186
=== "SSE HttpClient"
187187

@@ -192,7 +192,7 @@ McpTransport transport = new StdioClientTransport(params, McpJsonDefaults.getMap
192192
```
193193
=== "SSE WebClient (external)"
194194

195-
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`):
196196

197197
```java
198198
WebClient.Builder webClientBuilder = WebClient.builder()

‎docs/images/java-mcp-client-architecture.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎docs/images/java-mcp-server-architecture.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎docs/images/mcp-stack.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎docs/index.md‎

Lines changed: 34 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -10,42 +10,43 @@ Use it to build MCP clients and MCP servers in Java 17 or later, with a synchron
1010

1111
The SDK implements two generations of the protocol, side by side in the same module:
1212

13-
- **Classic**, for the [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) specification and earlier revisions, where client and server keep a session.
1413
- **Modern**, for the stateless [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) specification, where every request stands alone.
14+
- **Legacy**, for the [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25) specification and earlier revisions, where client and server keep a session.
1515

16-
See [Classic or Modern?](overview.md#classic-or-modern) to choose between them.
16+
The names are the specification's own, and legacy does not mean deprecated here: the SDK supports both.
17+
See [Modern or Legacy?](overview.md#modern-or-legacy) to choose between them.
1718

1819
## Features
1920

2021
What each implementation supports:
2122

22-
| Feature | Classic | Modern |
23+
| Feature | Modern | Legacy |
2324
|---|---|---|
2425
| [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools): discovery, calls, structured output | Yes | Yes |
2526
| [Resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources) and URI templates | Yes | Yes |
2627
| [Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts) | Yes | Yes |
2728
| [Completions](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/completion) for argument values | Yes | Yes |
28-
| [Elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation): asking the user for input | Yes, as a request from the server | Yes, as a multi round-trip request (form and URL) |
29-
| [Sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling) | Yes | Server only |
30-
| [Roots](https://modelcontextprotocol.io/specification/2025-11-25/client/roots) | Yes | Server only |
29+
| [Elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation): asking the user for input | Yes, as a multi round-trip request (form and URL) | Yes, as a request from the server |
30+
| [Sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling) | Server only | Yes |
31+
| [Roots](https://modelcontextprotocol.io/specification/2025-11-25/client/roots) | Server only | Yes |
3132
| [Progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress) notifications | Yes | Yes |
32-
| [Logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) | Yes | No (deprecated by the revision) |
33-
| Change notifications | Yes, over the session | Yes, with `subscriptions/listen` |
34-
| Finding out what a server supports | `initialize` handshake | `server/discover` |
35-
| Caching hints on results | No | Yes |
36-
| Custom HTTP headers for tool arguments (SEP-2243) | No | Yes |
33+
| [Logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) | No (deprecated by the revision) | Yes |
34+
| Change notifications | Yes, with `subscriptions/listen` | Yes, over the session |
35+
| Finding out what a server supports | `server/discover` | `initialize` handshake |
36+
| Caching hints on results | Yes | No |
37+
| Custom HTTP headers for tool arguments (SEP-2243) | Yes | No |
3738

3839
Both implementations share the following:
3940

4041
- **Sync and async APIs.** Choose blocking calls or Project Reactor types.
41-
- **Transports without a web framework.** STDIO, and Streamable HTTP on the JDK `HttpClient` (client) and the Servlet API (server). The classic implementation also has the legacy [SSE](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) transport.
42+
- **Transports without a web framework.** STDIO, and Streamable HTTP on the JDK `HttpClient` (client) and the Servlet API (server). The legacy implementation also has the deprecated [SSE](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports) transport.
4243
- **Pluggable JSON serialization.** Jackson 3.x by default, or Jackson 2.x.
4344
- **Security hooks.** Pluggable authorization hooks, and opt-in DNS rebinding protection with Host/Origin header validation (see [HTTP Transport Security](server.md#http-transport-security)).
4445

4546
!!! tip "Spring applications"
46-
Spring WebFlux and WebMVC transports for the classic client and server are part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ and are not shipped by this SDK.
47-
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 the [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.
48-
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).
47+
Spring WebFlux and WebMVC transports for the legacy client and server are part of [Spring AI](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-overview.html) 2.0+ and are not shipped by this SDK.
48+
Use the [MCP Client Boot Starter](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-client-boot-starter-docs.html) and the [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-server-boot-starter-docs.html) from Spring AI.
49+
Also consider the [MCP Annotations](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-annotations-overview.html) and [MCP Security](https://docs.spring.io/spring-ai/reference/2.1.0-SNAPSHOT/api/mcp/mcp-security.html).
4950

5051
## Getting Started
5152

@@ -64,52 +65,51 @@ The [Quickstart](quickstart.md) covers versions, the BOM, Gradle, and the other
6465

6566
<div class="grid cards" markdown>
6667

67-
- :rocket:{ .lg .middle } **Quickstart**
68+
- :material-sitemap:{ .lg .middle } **Overview**
6869

6970
---
7071

71-
Get started with dependencies and BOM configuration.
72+
Understand the architecture, and choose between modern and legacy.
7273

73-
[:octicons-arrow-right-24: Quickstart](quickstart.md)
74+
[:octicons-arrow-right-24: Overview](overview.md)
7475

75-
- :material-sitemap:{ .lg .middle } **Overview**
76+
- :rocket:{ .lg .middle } **Quickstart**
7677

7778
---
7879

79-
Understand the architecture, and choose between classic and modern.
80+
Get started with dependencies and BOM configuration.
8081

81-
[:octicons-arrow-right-24: Overview](overview.md)
82+
[:octicons-arrow-right-24: Quickstart](quickstart.md)
8283

83-
- :material-monitor:{ .lg .middle } **MCP Client (Classic)**
84+
- :material-monitor:{ .lg .middle } **MCP Client (Modern)**
8485

8586
---
8687

87-
Create and configure clients for servers of the 2025-11-25 revision and earlier.
88+
Call stateless servers of the 2026-07-28 revision.
8889

89-
[:octicons-arrow-right-24: Client](client.md)
90+
[:octicons-arrow-right-24: Client](client-modern.md)
9091

91-
- :material-server:{ .lg .middle } **MCP Server (Classic)**
92+
- :material-server:{ .lg .middle } **MCP Server (Modern)**
9293

9394
---
9495

95-
Implement and configure servers for the 2025-11-25 revision and earlier.
96+
Build stateless servers for the 2026-07-28 revision.
9697

97-
[:octicons-arrow-right-24: Server](server.md)
98+
[:octicons-arrow-right-24: Server](server-modern.md)
9899

99-
- :material-monitor:{ .lg .middle } **MCP Client (Modern)**
100+
- :material-monitor:{ .lg .middle } **MCP Client (Legacy)**
100101

101102
---
102103

103-
Call stateless servers of the 2026-07-28 revision.
104+
Create and configure clients for servers of the 2025-11-25 revision and earlier.
104105

105-
[:octicons-arrow-right-24: Client](client-modern.md)
106+
[:octicons-arrow-right-24: Client](client.md)
106107

107-
- :material-server:{ .lg .middle } **MCP Server (Modern)**
108+
- :material-server:{ .lg .middle } **MCP Server (Legacy)**
108109

109110
---
110111

111-
Build stateless servers for the 2026-07-28 revision.
112-
113-
[:octicons-arrow-right-24: Server](server-modern.md)
112+
Implement and configure servers for the 2025-11-25 revision and earlier.
114113

114+
[:octicons-arrow-right-24: Server](server.md)
115115
</div>

0 commit comments

Comments
 (0)