docs: examples + 2026-06 migration guide + changeset

Examples migrated to ctx.mcpReq.* (works under both protocols):
- toolWithSampleServer.ts: server.createMessage -> ctx.mcpReq.requestSampling
- elicitationFormExample.ts: server.elicitInput -> ctx.mcpReq.elicitInput (3x)
- serverGuide.examples.ts: server.listRoots -> ctx.mcpReq.listRoots
- elicitationUrlExample.ts: out-of-band webhook keeps server.elicitInput;
  comment documents pre-2026-only limitation (no request context).

Headline 2026-06 example:
- honoWebStandardStreamableHttp.ts: handleHttp(server.server, opts) Fetch
  handler. One shared instance, no Transport, no connect().
- simpleStatelessStreamableHttp.ts: shared instance + single connected
  transport (was per-request); transport per-message router serves both.

docs/migration.md + docs/migration-SKILL.md: 2026-06 stateless support
section. Server/Client are the same classes (additive); ctx.mcpReq.*
mapping table; auto-probe note; subscribe() note; LegacyTestClient pattern
for tests. No .legacy/LegacyServer references (sectioned approach).

docs/server.md, examples/server/README.md: updated to match.
.changeset/stateless-2026-06.md: major bump core/server/client.

Satisfies: 2575-R1, 2567-R1, 2322-R1

Author: felixweinberger

.changeset/stateless-2026-06.md

@@ -0,0 +1,25 @@
+---
+'@modelcontextprotocol/core': major
+'@modelcontextprotocol/server': major
+'@modelcontextprotocol/client': major
+---
+
+2026-06 stateless protocol support (SEP-2575, SEP-2567, SEP-2322).
+
+`Server` and `Client` now support the 2026-06 stateless connection model
+alongside the existing pre-2026 model. They remain the same classes (still
+extending `Protocol`); the new behavior is additive.
+
+- `Client.connect()` auto-probes `server/discover` and falls back to the
+  legacy `initialize` handshake.
+- `Server` gained `subscriptions` and `statelessHandlers()`; transports route
+  per-message via the `MCP-Protocol-Version` header / `_meta` key.
+- `handleHttp(server, opts)` is a new Fetch-API entry point: one shared
+  `Server` instance, no `Transport`, no `connect()`.
+- `client.subscribe(filter)` opens a `subscriptions/listen` stream.
+- `Transport` interface gained optional `setStatelessHandlers?` and
+  `sendAndReceive?` for custom transports.
+- Prefer `ctx.mcpReq.{elicitInput, requestSampling, listRoots, log}` inside
+  handlers; works under both protocols (MRTR under 2026-06).
+
+See `docs/migration.md` for the full guide.

CLAUDE.md

@@ -161,7 +161,6 @@ When a request arrives from the remote side:
 1. **Transport** receives message, calls `transport.onmessage()`
 2. **`Protocol.connect()`** routes to `_onrequest()`, `_onresponse()`, or `_onnotification()`
 3. **`Protocol._onrequest()`**:
-    - Looks up handler in `_requestHandlers` map (keyed by method name)
     - Creates `BaseContext` with `signal`, `sessionId`, `sendNotification`, `sendRequest`, etc.
     - Calls `buildContext()` to let subclasses enrich the context (e.g., Server adds HTTP request info)
     - Calls `dispatcher.dispatch()` which looks up the handler (keyed by method name), runs the middleware chain, invokes the handler, and wraps the result as a JSON-RPC response

docs/migration-SKILL.md

@@ -524,7 +524,31 @@ Access validators explicitly:
 - AJV (Node.js): `import { AjvJsonSchemaValidator } from '@modelcontextprotocol/server';`
 - CF Worker: `import { CfWorkerJsonSchemaValidator } from '@modelcontextprotocol/server/validators/cf-worker';`
 
-## 15. Migration Steps (apply in this order)
+## 15. 2026-06 Stateless Support (SEP-2575/2567/2322)
+
+`Server`/`Client` are the same classes (still extend `Protocol`); 2026-06 support is additive. `Client.connect()` auto-probes `server/discover` and falls back to legacy `initialize`. `setRequestHandler` is unchanged.
+
+**Prefer `ctx.mcpReq.*` inside handlers** (works under both protocols). Inside tool/prompt/resource handler bodies where `ctx` (the handler's second argument) is in scope, replace `<expr>.server.X()` (or `server.X()` on a low-level `Server`) with `ctx.mcpReq.X()`. The `<expr>` prefix varies (`mcpServer.server`, `this.server`, just `server`), so search for `.X(` and rewrite by hand:
+
+| Find calls to | Replace with |
+| --- | --- |
+| `.createMessage(` | `ctx.mcpReq.requestSampling(` |
+| `.elicitInput(` | `ctx.mcpReq.elicitInput(` |
+| `.listRoots(` | `ctx.mcpReq.listRoots(` |
+| `.sendLoggingMessage({ level, data })` | `ctx.mcpReq.log(level, data)` |
+| `.getClientCapabilities()` | `ctx.clientCapabilities` |
+
+Add `ctx` to the handler signature if not already present. For tools with an `inputSchema`: `async (args) =>` → `async (args, ctx) =>`. For tools WITHOUT an `inputSchema`: `async () =>` → `async ctx =>` (single parameter).
+
+The top-level `server.createMessage()` etc. still work with a connected pre-2026 client; this migration is recommended but not required.
+
+`ctx.mcpReq.requestSampling` keeps the same overload narrowing as `server.createMessage`: when `params.tools` is statically present the result type is `CreateMessageResultWithTools`; when statically absent it is `CreateMessageResult`. If `tools` is conditional at the call site, the result is the union; add a runtime `Array.isArray(result.content)` check before indexing.
+
+MRTR via `InputRequiredError` works for handlers registered via `setRequestHandler`; `fallbackRequestHandler` is not wrapped by middleware (matches pre-existing behavior).
+
+For tests that exercise pre-2026 connection-model behavior, construct the test client with `supportedProtocolVersions` filtered to pre-2026 versions only.
+
+## 16. Migration Steps (apply in this order)
 
 1. Update `package.json`: `npm uninstall @modelcontextprotocol/sdk`, install the appropriate v2 packages
 2. Replace all imports from `@modelcontextprotocol/sdk/...` using the import mapping tables (sections 3-4), including `StreamableHTTPServerTransport` → `NodeStreamableHTTPServerTransport`
@@ -536,4 +560,5 @@ Access validators explicitly:
 8. If using server SSE transport, migrate to Streamable HTTP
 9. If using server auth from the SDK: RS helpers (`requireBearerAuth`, `mcpAuthMetadataRouter`) → `@modelcontextprotocol/express`; AS helpers → external IdP/OAuth library
 10. If relying on `listTools()`/`listPrompts()`/etc. throwing on missing capabilities, set `enforceStrictCapabilities: true`
-11. Verify: build with `tsc` / run tests
+11. Inside tool/prompt/resource handlers, replace `server.createMessage`/`elicitInput`/`listRoots`/`sendLoggingMessage` with `ctx.mcpReq.*` per section 15
+12. Verify: build with `tsc` / run tests

docs/migration.md

@@ -874,6 +874,42 @@ There is no migration path for the removed surface; it was always `@experimental
 
 `TaskCreationParams.ttl` (the storage-layer creation parameter) is now `number | undefined`; `null` is no longer accepted. Per the MCP spec, `null` TTL (unlimited lifetime) is only valid in server responses (`Task.ttl`), not in creation requests. Omit `ttl` to let the store decide. This is a storage-interface change and is independent of the Protocol-level removals above.
 
+## 2026-06 Stateless Protocol Support (SEP-2575, SEP-2567, SEP-2322)
+
+`Server` and `Client` now support the 2026-06 stateless connection model alongside the existing pre-2026 model. They remain the same classes (still extending `Protocol`); the new behavior is additive.
+
+### What changed
+
+- **`Client.connect()` auto-probes.** On connect, the client sends `server/discover` via the transport's `sendAndReceive` path. If the server responds, the client operates in stateless mode; typed methods (`callTool`, `listTools`, etc.) route via `sendAndReceive` and the MRTR loop. If discover fails (server doesn't support it, transport doesn't have `sendAndReceive`), the client falls back to the legacy `initialize` handshake. Existing code works unchanged.
+- **`Server` gained a stateless dispatch path.** `server.statelessHandlers()` returns `{dispatch, listen}` for transports to call. `connect(transport)` wires this automatically via `transport.setStatelessHandlers?.()`. Handlers registered with `setRequestHandler` serve both paths.
+- **`handleHttp(server, opts)`** is a new Fetch-API entry point: one shared `Server` instance, no `Transport`, no `connect()`. Returns `(Request) => Promise<Response>`. See `examples/server/src/honoWebStandardStreamableHttp.ts`.
+- **`client.subscribe(filter)`** opens a `subscriptions/listen` stream for list-changed and resource-updated notifications (the 2026-06 replacement for unsolicited notifications and `resources/subscribe`).
+- **`Transport` interface gained two optional methods:** `setStatelessHandlers?(handlers)` (server side) and `sendAndReceive?(req, opts?)` (client side). Implement these in custom transports to support 2026-06.
+
+### Prefer `ctx.mcpReq.*` for server-to-client interactions
+
+Inside a tool/prompt/resource handler, use `ctx.mcpReq.{elicitInput, requestSampling, listRoots, log}` instead of the top-level `server.elicitInput()` / `server.createMessage()` / `server.listRoots()` / `server.sendLoggingMessage()`. The `ctx.mcpReq.*` form works under **both** protocols: with a pre-2026 client it sends a real request; with a 2026-06 client it returns an `input_required` result and the client retries with the response embedded (SEP-2322 MRTR).
+
+| Top-level (pre-2026 only) | Handler-context (both protocols) |
+| --- | --- |
+| `server.createMessage(params)` | `ctx.mcpReq.requestSampling(params)` |
+| `server.elicitInput(params)` | `ctx.mcpReq.elicitInput(params)` |
+| `server.listRoots()` | `ctx.mcpReq.listRoots()` |
+| `server.sendLoggingMessage({level, data})` | `ctx.mcpReq.log(level, data)` |
+| `server.getClientCapabilities()` | `ctx.clientCapabilities` |
+
+The top-level methods still exist and work when a pre-2026 client is connected. They are not removed.
+
+MRTR via `InputRequiredError` works for handlers registered via `setRequestHandler`; `fallbackRequestHandler` is not wrapped by middleware (matches pre-existing behavior).
+
+### Tests pinning pre-2026
+
+If a test exercises pre-2026 connection-model behavior (e.g., `oninitialized`, server-initiated requests, in-band logging) and breaks because the auto-probe now succeeds, construct the client with `supportedProtocolVersions` filtered to pre-2026 versions only, or use a fixture like `LegacyTestClient` that does so. The probe falls back to legacy when no mutual stateless version exists.
+
+### Shared instances
+
+A single `Server` instance can safely serve many concurrent 2026-06 clients via `handleHttp` or a connected transport's per-message router. For pre-2026 clients, the existing per-session guidance still applies (the legacy path's `_clientCapabilities` is per-connection state).
+
 ## Enhancements
 
 ### Automatic JSON Schema validator selection by runtime

docs/server.md

@@ -478,7 +478,7 @@ For runnable examples, see [`elicitationFormExample.ts`](https://github.com/mode
 
 ### Roots
 
-Roots let a tool handler discover the client's workspace directories — for example, to scope a file search or identify project boundaries (see [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) in the MCP overview). Call {@linkcode @modelcontextprotocol/server!server/server.Server#listRoots | server.server.listRoots()} (requires the client to declare the `roots` capability):
+Roots let a tool handler discover the client's workspace directories — for example, to scope a file search or identify project boundaries (see [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) in the MCP overview). Call `ctx.mcpReq.listRoots()` inside the handler (requires the client to declare the `roots` capability). This works under both the pre-2026 connection model and the 2026 stateless model:
 
 ```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_roots"
 server.registerTool(
@@ -487,8 +487,8 @@ server.registerTool(
         description: 'List files across all workspace roots',
         inputSchema: z.object({})
     },
-    async (_args, _ctx): Promise<CallToolResult> => {
-        const { roots } = await server.server.listRoots();
+    async (_args, ctx): Promise<CallToolResult> => {
+        const { roots } = await ctx.mcpReq.listRoots();
         const summary = roots.map(r => `${r.name ?? r.uri}: ${r.uri}`).join('\n');
         return { content: [{ type: 'text', text: summary }] };
     }

examples/server/README.md

@@ -28,15 +28,15 @@ pnpm tsx src/simpleStreamableHttp.ts
 | Scenario                                  | Description                                                                                  | File                                                                                     |
 | ----------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | Streamable HTTP server (stateful)         | Feature-rich server with tools/resources/prompts, logging, sampling, and optional OAuth.     | [`src/simpleStreamableHttp.ts`](src/simpleStreamableHttp.ts)                             |
-| Streamable HTTP server (stateless)        | No session tracking; good for simple API-style servers.                                      | [`src/simpleStatelessStreamableHttp.ts`](src/simpleStatelessStreamableHttp.ts)           |
+| Streamable HTTP server (stateless)        | Shared instance for 2026-06 clients. Pre-2026 clients need per-session (see stateful row).   | [`src/simpleStatelessStreamableHttp.ts`](src/simpleStatelessStreamableHttp.ts)           |
 | Resource-Server-only auth                 | Minimal OAuth RS using SDK's `mcpAuthMetadataRouter` + `requireBearerAuth` (no better-auth). | [`src/resourceServerOnly.ts`](src/resourceServerOnly.ts)                                 |
 | JSON response mode (no SSE)               | Streamable HTTP with JSON-only responses and limited notifications.                          | [`src/jsonResponseStreamableHttp.ts`](src/jsonResponseStreamableHttp.ts)                 |
 | Server notifications over Streamable HTTP | Demonstrates server-initiated notifications via GET+SSE.                                     | [`src/standaloneSseWithGetStreamableHttp.ts`](src/standaloneSseWithGetStreamableHttp.ts) |
 | Output schema server                      | Demonstrates tool output validation with structured output schemas.                          | [`src/mcpServerOutputSchema.ts`](src/mcpServerOutputSchema.ts)                           |
 | Form elicitation server                   | Collects **non-sensitive** user input via schema-driven forms.                               | [`src/elicitationFormExample.ts`](src/elicitationFormExample.ts)                         |
 | URL elicitation server                    | Secure browser-based flows for **sensitive** input (API keys, OAuth, payments).              | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                           |
 | Sampling server                           | Demonstrates server-initiated sampling requests.                                             | [`src/toolWithSampleServer.ts`](src/toolWithSampleServer.ts)                             |
-| Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                   | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
+| Hono `handleHttp` server (2026-06)        | Headline 2026-06 stateless entry: `handleHttp()` Fetch handler, no Transport, no connect().  | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
 | SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
 
 ## OAuth demo flags (Streamable HTTP server)

examples/server/src/elicitationFormExample.ts

@@ -36,10 +36,12 @@ const getServer = () => {
         {
             description: 'Register a new user account by collecting their information'
         },
-        async () => {
+        async ctx => {
             try {
-                // Request user information through form elicitation
-                const result = await mcpServer.server.elicitInput({
+                // Request user information through form elicitation.
+                // ctx.mcpReq.elicitInput works under both the pre-2026 connection
+                // model and the 2026 stateless model (MRTR). See SEP-2322.
+                const result = await ctx.mcpReq.elicitInput({
                     mode: 'form',
                     message: 'Please provide your registration information:',
                     requestedSchema: {
@@ -134,10 +136,10 @@ const getServer = () => {
         {
             description: 'Create a calendar event by collecting event details'
         },
-        async () => {
+        async ctx => {
             try {
                 // Step 1: Collect basic event information
-                const basicInfo = await mcpServer.server.elicitInput({
+                const basicInfo = await ctx.mcpReq.elicitInput({
                     mode: 'form',
                     message: 'Step 1: Enter basic event information',
                     requestedSchema: {
@@ -166,7 +168,7 @@ const getServer = () => {
                 }
 
                 // Step 2: Collect date and time
-                const dateTime = await mcpServer.server.elicitInput({
+                const dateTime = await ctx.mcpReq.elicitInput({
                     mode: 'form',
                     message: 'Step 2: Enter date and time',
                     requestedSchema: {
@@ -238,9 +240,9 @@ const getServer = () => {
         {
             description: 'Update shipping address with validation'
         },
-        async () => {
+        async ctx => {
             try {
-                const result = await mcpServer.server.elicitInput({
+                const result = await ctx.mcpReq.elicitInput({
                     mode: 'form',
                     message: 'Please provide your shipping address:',
                     requestedSchema: {

examples/server/src/elicitationUrlExample.ts

@@ -577,6 +577,11 @@ const mcpPostHandler = async (req: Request, res: Response) => {
                     // This avoids race conditions where requests might come in before the session is stored
                     console.log(`Session initialized with ID: ${sessionId}`);
                     transports[sessionId] = transport;
+                    // Out-of-band webhook callbacks have no request context, so this
+                    // calls server.elicitInput directly. This pattern requires a
+                    // connected pre-2026 client; under the 2026 stateless model
+                    // there is no session to send to. Prefer ctx.mcpReq.elicitInput
+                    // inside a tool/prompt handler when possible.
                     sessionsNeedingElicitation[sessionId] = {
                         elicitationSender: params => server.server.elicitInput(params),
                         createCompletionNotifier: elicitationId => server.server.createElicitationCompletionNotifier(elicitationId)