feat(core): deprecate sessionId on base Transport/BaseContext; legacySessionId() helper (SEP-2567)

Author: felixweinberger

docs/migration.md

@@ -573,6 +573,24 @@ import { JSONRPCError, ResourceReference, isJSONRPCError } from '@modelcontextpr
 import { JSONRPCErrorResponse, ResourceTemplateReference, isJSONRPCErrorResponse } from '@modelcontextprotocol/server';
 ```
 
+### `sessionId` deprecated (SEP-2567)
+
+`ctx.sessionId` and `Transport.sessionId` are deprecated. Sessions are extension-track per SEP-2567; 2026-06+ clients will not send `Mcp-Session-Id`. The fields remain (optional, as before) but will be `undefined` for stateless clients.
+
+**Do not key application state on `sessionId`.** Key on the validated principal instead:
+
+```ts
+// Before (silently shares state across stateless clients)
+const prefs = perSession.get(ctx.sessionId);
+
+// After
+const principal = ctx.http?.authInfo?.token;
+if (!principal) throw new ProtocolError(ProtocolErrorCode.InvalidRequest, 'auth required');
+const prefs = perPrincipal.get(principal);
+```
+
+Use `legacySessionId(transport)` for an explicit-intent read where session-mode compat is needed.
+
 ### Request handler context types
 
 The `RequestHandlerExtra` type has been replaced with a structured context type hierarchy using nested groups:

packages/core/src/exports/public/index.ts

@@ -70,7 +70,7 @@ export { deserializeMessage, ReadBuffer, serializeMessage } from '../../shared/s
 
 // Transport types (NOT normalizeHeaders)
 export type { FetchLike, Transport, TransportSendOptions } from '../../shared/transport.js';
-export { createFetchWithInit } from '../../shared/transport.js';
+export { createFetchWithInit, legacySessionId } from '../../shared/transport.js';
 export { InMemoryTransport } from '../../util/inMemory.js';
 
 // URI Template

packages/core/src/shared/context.ts

@@ -112,6 +112,8 @@ export type NotificationOptions = {
 export type BaseContext = {
     /**
      * The session ID from the transport, if available.
+     * @deprecated Sessions are extension-track per SEP-2567; 2026-06+ clients will not
+     *   send `Mcp-Session-Id`. Key application state on `ctx.http?.authInfo`, not session-id.
      */
     sessionId?: string;
 
@@ -265,7 +267,11 @@ export type RequestEnv = {
     /** Abort signal for the inbound request. If omitted, a fresh controller is created. */
     signal?: AbortSignal;
 
-    /** Transport session identifier (legacy `Mcp-Session-Id`). */
+    /**
+     * Transport session identifier (legacy `Mcp-Session-Id`).
+     * @deprecated Sessions are extension-track per SEP-2567. Populate `ext.sessionId` for
+     *   compat modules that need it; new code should not depend on this.
+     */
     sessionId?: string;
 
     /**

packages/core/src/shared/transport.ts

@@ -118,6 +118,9 @@ export interface Transport {
 
     /**
      * The session ID generated for this connection.
+     * @deprecated Sessions are extension-track per SEP-2567; 2026-06+ clients will not
+     *   send `Mcp-Session-Id`. Key application state on `ctx.http?.authInfo`, not session-id.
+     *   Read via {@linkcode legacySessionId} for an explicit signal.
      */
     sessionId?: string | undefined;
 
@@ -132,3 +135,13 @@ export interface Transport {
      */
     setSupportedProtocolVersions?: ((versions: string[]) => void) | undefined;
 }
+
+/**
+ * Read `sessionId` from a transport if it exposes one. Explicit-intent helper for
+ * SEP-2567: sessions are extension-track and `undefined` for 2026-06+ clients.
+ * Prefer keying application state on `ctx.http?.authInfo`; use this only when interoperating
+ * with pre-2026-06 clients that send `Mcp-Session-Id`.
+ */
+export function legacySessionId(t: Transport | undefined): string | undefined {
+    return t?.sessionId;
+}