feat(core,server): expose the per-request envelope on the request handler context

.changeset/per-request-envelope-on-handler-context.md

@@ -0,0 +1,7 @@
+---
+'@modelcontextprotocol/core': patch
+'@modelcontextprotocol/server': patch
+---
+
+Request handlers can now read the protocol version governing the current request from their context (`ctx.mcpReq.protocolVersion`, both client and server handlers), and server handlers can read the calling client's declared capabilities and implementation info
+(`ctx.client.capabilities`, `ctx.client.info`). `getNegotiatedProtocolVersion()` is now declared on `Protocol`, so both roles expose it.

docs/client.md

@@ -487,6 +487,23 @@ client.setRequestHandler('roots/list', async () => {
 
 When the available roots change, notify the server with {@linkcode @modelcontextprotocol/client!client/client.Client#sendRootsListChanged | client.sendRootsListChanged()}.
 
+### Request context
+
+Handlers receive the request context (`ctx`) as their second argument. `ctx.mcpReq.protocolVersion` (from {@linkcode @modelcontextprotocol/client!index.BaseContext | BaseContext}) is the protocol version governing the request:
+
+```ts source="../examples/client/src/clientGuide.examples.ts#requestContext_handler"
+client.setRequestHandler('sampling/createMessage', async (request, ctx) => {
+    console.log(`Sampling request under MCP ${ctx.mcpReq.protocolVersion}:`, request.params.messages.at(-1));
+
+    // In production, send messages to your LLM here
+    return {
+        model: 'my-model',
+        role: 'assistant' as const,
+        content: { type: 'text' as const, text: 'Response from the model' }
+    };
+});
+```
+
 ## Error handling
 
 ### Tool errors vs protocol errors

docs/migration.md

@@ -602,6 +602,8 @@ The `RequestHandlerExtra` type has been replaced with a structured context type
 | `extra.taskStore`                        | `ctx.task?.store`                                                      |
 | `extra.taskId`                           | `ctx.task?.id`                                                         |
 | `extra.taskRequestedTtl`                 | `ctx.task?.requestedTtl`                                               |
+| — (new in v2)                            | `ctx.mcpReq.protocolVersion`                                           |
+| — (new in v2)                            | `ctx.client.capabilities`, `ctx.client.info` (only on `ServerContext`) |
 
 **Before (v1):**
 
@@ -627,9 +629,10 @@ server.setRequestHandler('tools/call', async (request, ctx) => {
 
 Context fields are organized into 4 groups:
 
-- **`mcpReq`** — request-level concerns: `id`, `method`, `_meta`, `signal`, `send()`, `notify()`, plus server-only `log()`, `elicitInput()`, and `requestSampling()`
+- **`mcpReq`** — request-level concerns: `id`, `method`, `protocolVersion`, `_meta`, `signal`, `send()`, `notify()`, plus server-only `log()`, `elicitInput()`, and `requestSampling()`
 - **`http?`** — HTTP transport concerns (undefined for stdio): `authInfo`, plus server-only `req`, `closeSSE`, `closeStandaloneSSE`
 - **`task?`** — task lifecycle: `id`, `store`, `requestedTtl`
+- **`client`** — server-only: the calling client's declared `capabilities` and implementation `info`
 
 `BaseContext` is the common base type shared by both `ServerContext` and `ClientContext`. `ServerContext` extends each group with server-specific additions via type intersection.
 

docs/server.md

@@ -495,6 +495,51 @@ server.registerTool(
 );
 ```
 
+## Reading request context
+
+Every handler receives the request context (`ctx`) as its second argument. Beyond the helpers shown above, it carries per-request facts about the caller:
+
+- `ctx.mcpReq.protocolVersion` (from {@linkcode @modelcontextprotocol/server!index.BaseContext | BaseContext}) — the protocol version governing the request.
+- `ctx.client.capabilities` and `ctx.client.info` (from {@linkcode @modelcontextprotocol/server!index.ServerContext | ServerContext}) — the calling client's declared capabilities and implementation info.
+
+Check `ctx.client.capabilities` before sending a [server-initiated request](#server-initiated-requests) so you never ask a client to do something it cannot — for example, only [elicit input](#elicitation) when the client declared the `elicitation` capability:
+
+```ts source="../examples/server/src/serverGuide.examples.ts#registerTool_requestContext"
+server.registerTool(
+    'delete-records',
+    {
+        description: 'Delete records, asking for confirmation when the client supports it',
+        inputSchema: z.object({ table: z.string() })
+    },
+    async ({ table }, ctx): Promise<CallToolResult> => {
+        // Per-request facts: the calling client and the protocol version governing this request
+        const caller = `${ctx.client.info?.name ?? 'unknown client'} (MCP ${ctx.mcpReq.protocolVersion})`;
+
+        // Only ask for confirmation if the calling client declared the elicitation capability
+        if (ctx.client.capabilities.elicitation) {
+            const result = await ctx.mcpReq.elicitInput({
+                mode: 'form',
+                message: `Delete all records in ${table}?`,
+                requestedSchema: {
+                    type: 'object',
+                    properties: { confirm: { type: 'boolean', title: 'Confirm' } },
+                    required: ['confirm']
+                }
+            });
+            if (result.action !== 'accept' || result.content?.confirm !== true) {
+                return { content: [{ type: 'text', text: 'Deletion cancelled.' }] };
+            }
+        }
+
+        // ... delete records, attributing the request to `caller` ...
+        return { content: [{ type: 'text', text: `Deleted all records in ${table} (requested by ${caller})` }] };
+    }
+);
+```
+
+> [!IMPORTANT]
+> Capabilities are declarations, not authorization. Never use them to gate access to tools, resources, or data — that is the authorization layer's job.
+
 ## Tasks (experimental)
 
 > [!WARNING]

examples/client/src/clientGuide.examples.ts

@@ -437,6 +437,22 @@ function roots_handler(client: Client) {
     //#endregion roots_handler
 }
 
+/** Example: Read the governing protocol version from the handler context. */
+function requestContext_handler(client: Client) {
+    //#region requestContext_handler
+    client.setRequestHandler('sampling/createMessage', async (request, ctx) => {
+        console.log(`Sampling request under MCP ${ctx.mcpReq.protocolVersion}:`, request.params.messages.at(-1));
+
+        // In production, send messages to your LLM here
+        return {
+            model: 'my-model',
+            role: 'assistant' as const,
+            content: { type: 'text' as const, text: 'Response from the model' }
+        };
+    });
+    //#endregion requestContext_handler
+}
+
 // ---------------------------------------------------------------------------
 // Error handling
 // ---------------------------------------------------------------------------
@@ -568,6 +584,7 @@ void capabilities_declaration;
 void sampling_handler;
 void elicitation_handler;
 void roots_handler;
+void requestContext_handler;
 void errorHandling_toolErrors;
 void errorHandling_lifecycle;
 void errorHandling_timeout;

examples/server/src/serverGuide.examples.ts

@@ -419,6 +419,46 @@
     //#endregion registerTool_roots
 }
 
+// ---------------------------------------------------------------------------
+// Reading request context
+// ---------------------------------------------------------------------------
+
+/** Example: Tool that reads per-request facts (protocol version, client capabilities) from the handler context. */
+function registerTool_requestContext(server: McpServer) {
+    //#region registerTool_requestContext
+    server.registerTool(
+        'delete-records',
+        {
+            description: 'Delete records, asking for confirmation when the client supports it',
+            inputSchema: z.object({ table: z.string() })
+        },
+        async ({ table }, ctx): Promise<CallToolResult> => {
+            // Per-request facts: the calling client and the protocol version governing this request
+            const caller = `${ctx.client.info?.name ?? 'unknown client'} (MCP ${ctx.mcpReq.protocolVersion})`;
+
+            // Only ask for confirmation if the calling client declared the elicitation capability
+            if (ctx.client.capabilities.elicitation) {
+                const result = await ctx.mcpReq.elicitInput({
+                    mode: 'form',
+                    message: `Delete all records in ${table}?`,
+                    requestedSchema: {
+                        type: 'object',
+                        properties: { confirm: { type: 'boolean', title: 'Confirm' } },
+                        required: ['confirm']
+                    }
+                });
+                if (result.action !== 'accept' || result.content?.confirm !== true) {
+                    return { content: [{ type: 'text', text: 'Deletion cancelled.' }] };
+                }
+            }
+
+            // ... delete records, attributing the request to `caller` ...
+            return { content: [{ type: 'text', text: `Deleted all records in ${table} (requested by ${caller})` }] };
+        }
+    );
+    //#endregion registerTool_requestContext
+}
+
 // ---------------------------------------------------------------------------
 // Transports
 // ---------------------------------------------------------------------------
@@ -546,6 +586,7 @@
 void registerTool_sampling;
 void registerTool_elicitation;
 void registerTool_roots;
+void registerTool_requestContext;
 void registerResource_static;
 void registerResource_template;
 void registerPrompt_basic;

packages/client/src/client/client.ts

@@ -225,7 +225,6 @@ export type ClientOptions = ProtocolOptions & {
 export class Client extends Protocol<ClientContext> {
     private _serverCapabilities?: ServerCapabilities;
     private _serverVersion?: Implementation;
-    private _negotiatedProtocolVersion?: string;
     private _capabilities: ClientCapabilities;
     private _instructions?: string;
     private _jsonSchemaValidator: jsonSchemaValidator;
@@ -554,15 +553,6 @@ export class Client extends Protocol<ClientContext> {
         return this._serverVersion;
     }
 
-    /**
-     * After initialization has completed, this will be populated with the protocol version negotiated
-     * during the initialize handshake. When manually reconstructing a transport for reconnection, pass this
-     * value to the new transport so it continues sending the required `mcp-protocol-version` header.
-     */
-    getNegotiatedProtocolVersion(): string | undefined {
-        return this._negotiatedProtocolVersion;
-    }
-
     /**
      * After initialization has completed, this may be populated with information about the server's instructions.
      */

packages/core/src/shared/protocol.ts

@@ -9,6 +9,7 @@ import type {
     ElicitRequestFormParams,
     ElicitRequestURLParams,
     ElicitResult,
+    Implementation,
     JSONRPCErrorResponse,
     JSONRPCNotification,
     JSONRPCRequest,
@@ -33,6 +34,7 @@ import type {
     TaskCreationParams
 } from '../types/index.js';
 import {
+    DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
     getNotificationSchema,
     getRequestSchema,
     getResultSchema,
@@ -185,6 +187,18 @@ export type BaseContext = {
          */
         method: string;
 
+        /**
+         * The protocol version governing this request.
+         *
+         * Resolved per request from the source the governing protocol revision defines: the initialize
+         * handshake for 2025-line revisions; the request's own `_meta` for revisions that carry a
+         * per-request envelope. Sources never mix and never fall back.
+         *
+         * For requests that arrive before the initialize handshake completes (where only `ping` is legal),
+         * this is the SDK's {@linkcode DEFAULT_NEGOTIATED_PROTOCOL_VERSION}.
+         */
+        protocolVersion: string;
+
         /**
          * Metadata from the original request.
          */
@@ -282,6 +296,32 @@ export type ServerContext = BaseContext & {
          */
         closeStandaloneSSE?: () => void;
     };
+
+    /**
+     * Facts about the client that is calling this request.
+     *
+     * The values are resolved per request from the source the governing protocol revision defines: the
+     * initialize handshake for 2025-line revisions; the request's own `_meta` for revisions that carry a
+     * per-request envelope. Sources never mix and never fall back. For requests that arrive before the
+     * initialize handshake completes (where only `ping` is legal), `capabilities` is `{}` and `info` is
+     * `undefined`.
+     *
+     * Capabilities are declarations, not authorization: this exists so the server does not ask a client to
+     * do something it cannot (e.g. elicitation). It MUST NOT be used to gate access to tools, resources, or
+     * data — that is the authorization layer's job.
+     */
+    client: {
+        /**
+         * The capabilities the calling client declared. `{}` before the initialize handshake completes.
+         */
+        capabilities: ClientCapabilities;
+
+        /**
+         * The calling client's implementation name and version, or `undefined` before the initialize
+         * handshake completes.
+         */
+        info: Implementation | undefined;
+    };
 };
 
 /**
@@ -323,6 +363,13 @@ export abstract class Protocol<ContextT extends BaseContext> {
 
     protected _supportedProtocolVersions: string[];
 
+    /**
+     * The protocol version negotiated for the current connection, set by the concrete role at its
+     * negotiation point (the client when it receives InitializeResult; the server when it responds
+     * to initialize), or `undefined` before negotiation has completed.
+     */
+    protected _negotiatedProtocolVersion?: string;
+
     /**
      * Callback for when the connection is closed for any reason.
      *
@@ -408,6 +455,19 @@ export abstract class Protocol<ContextT extends BaseContext> {
      */
     protected abstract buildContext(ctx: BaseContext, transportInfo?: MessageExtraInfo): ContextT;
 
+    /**
+     * The protocol version negotiated for the current connection, or `undefined` before
+     * negotiation has completed.
+     *
+     * It is read per request when building the handler context to populate
+     * `ctx.mcpReq.protocolVersion`. On the client side, when manually reconstructing a transport for
+     * reconnection, pass this value to the new transport so it continues sending the required
+     * `mcp-protocol-version` header.
+     */
+    getNegotiatedProtocolVersion(): string | undefined {
+        return this._negotiatedProtocolVersion;
+    }
+
     private async _oncancel(notification: CancelledNotification): Promise<void> {
         if (!notification.params.requestId) {
             return;
@@ -607,6 +667,10 @@ export abstract class Protocol<ContextT extends BaseContext> {
             mcpReq: {
                 id: request.id,
                 method: request.method,
+                // Resolved from the source the governing revision defines. At present that is the
+                // initialize-handshake-negotiated version (exposed by the concrete role); requests that
+                // arrive before the handshake completes (only `ping` is legal there) get the SDK default.
+                protocolVersion: this.getNegotiatedProtocolVersion() ?? DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
                 _meta: request.params?._meta,
                 signal: abortController.signal,
                 // BaseContext.mcpReq.send is declared with two overloads (spec-method-keyed and explicit-schema). Arrow

packages/core/test/shared/protocol.test.ts

@@ -34,7 +34,7 @@ import type {
     Task,
     TaskCreationParams
 } from '../../src/types/index.js';
-import { ProtocolError, ProtocolErrorCode, RELATED_TASK_META_KEY } from '../../src/types/index.js';
+import { DEFAULT_NEGOTIATED_PROTOCOL_VERSION, ProtocolError, ProtocolErrorCode, RELATED_TASK_META_KEY } from '../../src/types/index.js';
 import { SdkError, SdkErrorCode } from '../../src/errors/sdkErrors.js';
 
 // Test Protocol subclass for testing
@@ -5678,3 +5678,54 @@ describe('TaskManager always present (NullTaskManager pattern)', () => {
         expect(mockClient.taskManager).toBe(mockTaskModule);
     });
 });
+
+describe('ctx.mcpReq.protocolVersion population', () => {
+    // Protocol subclass with a settable negotiated version, mirroring how Server/Client
+    // assign the inherited protected field at their negotiation points.
+    class NegotiatedVersionProtocol extends Protocol<BaseContext> {
+        set negotiated(version: string | undefined) {
+            this._negotiatedProtocolVersion = version;
+        }
+        protected assertCapabilityForMethod(): void {}
+        protected assertNotificationCapability(): void {}
+        protected assertRequestHandlerCapability(): void {}
+        protected assertTaskCapability(): void {}
+        protected assertTaskHandlerCapability(): void {}
+        protected buildContext(ctx: BaseContext): BaseContext {
+            return ctx;
+        }
+    }
+
+    async function captureProtocolVersion(p: NegotiatedVersionProtocol, t: MockTransport): Promise<string> {
+        await p.connect(t);
+        const captured = new Promise<string>(resolve => {
+            p.setRequestHandler('ping', async (_request, ctx) => {
+                resolve(ctx.mcpReq.protocolVersion);
+                return {};
+            });
+        });
+        t.onmessage?.({ jsonrpc: '2.0', id: 1, method: 'ping', params: {} });
+        return captured;
+    }
+
+    test('falls back to the SDK default before the handshake completes', async () => {
+        const p = new NegotiatedVersionProtocol();
+        // negotiated is undefined: this models a request (only ping is legal) arriving pre-initialize.
+        const version = await captureProtocolVersion(p, new MockTransport());
+        expect(version).toBe(DEFAULT_NEGOTIATED_PROTOCOL_VERSION);
+    });
+
+    test('the base Protocol getter returns undefined so role-less subclasses get the default', async () => {
+        const p = createTestProtocol();
+        const t = new MockTransport();
+        await p.connect(t);
+        const captured = new Promise<string>(resolve => {
+            p.setRequestHandler('ping', async (_request, ctx) => {
+                resolve(ctx.mcpReq.protocolVersion);
+                return {};
+            });
+        });
+        t.onmessage?.({ jsonrpc: '2.0', id: 1, method: 'ping', params: {} });
+        expect(await captured).toBe(DEFAULT_NEGOTIATED_PROTOCOL_VERSION);
+    });
+});