docs: document the per-request envelope on the handler context

Author: felixweinberger

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 @@ function registerTool_roots(server: McpServer) {
     //#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_progress;
 void registerTool_sampling;
 void registerTool_elicitation;
 void registerTool_roots;
+void registerTool_requestContext;
 void registerResource_static;
 void registerResource_template;
 void registerPrompt_basic;