v2: Web standards Request object in ctx (#1822)

KKonstantinov · felixweinberger · web-flow · commit 2fd7f5ff265e · 2026-03-31T12:02:37.000+01:00
Co-authored-by: Felix Weinberger &lt;3823880+felixweinberger@users.noreply.github.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -164,7 +164,7 @@ When a request arrives from the remote side:
 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 `requestInfo`)
+    - Calls `buildContext()` to let subclasses enrich the context (e.g., Server adds HTTP request info)
     - Invokes handler, sends JSON-RPC response back via transport
 4. **Handler** was registered via `setRequestHandler('method', handler)`
 
diff --git a/docs/migration-SKILL.md b/docs/migration-SKILL.md
@@ -298,16 +298,17 @@ Note: the third argument (`metadata`) is required — pass `{}` if no metadata.
 
 ## 7. Headers API
 
-Transport constructors and `RequestInfo.headers` now use the Web Standard `Headers` object instead of plain objects.
+Transport constructors now use the Web Standard `Headers` object instead of plain objects. The custom `RequestInfo` type has been replaced with the standard Web `Request` object, giving access to headers, URL, query parameters, and method.
 
 ```typescript
-// v1: plain object, bracket access
+// v1: plain object, bracket access, custom RequestInfo
 headers: { 'Authorization': 'Bearer token' }
 extra.requestInfo?.headers['mcp-session-id']
 
-// v2: Headers object, .get() access
+// v2: Headers object, .get() access, standard Web Request
 headers: new Headers({ 'Authorization': 'Bearer token' })
 ctx.http?.req?.headers.get('mcp-session-id')
+new URL(ctx.http?.req?.url).searchParams.get('debug')
 ```
 
 ## 8. Removed Server Features
@@ -391,7 +392,7 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 | `extra.sendNotification(...)`    | `ctx.mcpReq.notify(...)`                                                   |
 | `extra.authInfo`                 | `ctx.http?.authInfo`                                                       |
 | `extra.sessionId`                | `ctx.sessionId`                                                            |
-| `extra.requestInfo`              | `ctx.http?.req` (only `ServerContext`)                                     |
+| `extra.requestInfo`              | `ctx.http?.req` (standard Web `Request`, only `ServerContext`)             |
 | `extra.closeSSEStream`           | `ctx.http?.closeSSE` (only `ServerContext`)                                |
 | `extra.closeStandaloneSSEStream` | `ctx.http?.closeStandaloneSSE` (only `ServerContext`)                      |
 | `extra.taskStore`                | `ctx.task?.store`                                                          |
diff --git a/docs/migration.md b/docs/migration.md
@@ -174,8 +174,12 @@ const transport = new StreamableHTTPClientTransport(url, {
     }
 });
 
-// Reading headers in a request handler
+// Reading headers in a request handler (ctx.http.req is the standard Web Request object)
 const sessionId = ctx.http?.req?.headers.get('mcp-session-id');
+
+// Reading query parameters
+const url = new URL(ctx.http!.req!.url);
+const debug = url.searchParams.get('debug');
 ```
 
 ### `McpServer.tool()`, `.prompt()`, `.resource()` removed
@@ -512,7 +516,7 @@ The `RequestHandlerExtra` type has been replaced with a structured context type
 | `extra.sendRequest(...)`                 | `ctx.mcpReq.send(...)`                                                 |
 | `extra.sendNotification(...)`            | `ctx.mcpReq.notify(...)`                                               |
 | `extra.authInfo`                         | `ctx.http?.authInfo`                                                   |
-| `extra.requestInfo`                      | `ctx.http?.req` (only on `ServerContext`)                              |
+| `extra.requestInfo`                      | `ctx.http?.req` (standard Web `Request`, only on `ServerContext`)     |
 | `extra.closeSSEStream`                   | `ctx.http?.closeSSE` (only on `ServerContext`)                         |
 | `extra.closeStandaloneSSEStream`         | `ctx.http?.closeStandaloneSSE` (only on `ServerContext`)               |
 | `extra.sessionId`                        | `ctx.sessionId`                                                        |
@@ -535,7 +539,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
 
 ```typescript
 server.setRequestHandler('tools/call', async (request, ctx) => {
-    const headers = ctx.http?.req?.headers;
+    const headers = ctx.http?.req?.headers; // standard Web Request object
     const taskStore = ctx.task?.store;
     await ctx.mcpReq.notify({ method: 'notifications/progress', params: { progressToken: 'abc', progress: 50, total: 100 } });
     return { content: [{ type: 'text', text: 'result' }] };
diff --git a/packages/core/src/shared/protocol.ts b/packages/core/src/shared/protocol.ts
@@ -24,7 +24,6 @@ import type {
     RelatedTaskMetadata,
     Request,
     RequestId,
-    RequestInfo,
     RequestMeta,
     RequestMethod,
     RequestTypeMap,
@@ -257,9 +256,9 @@ export type ServerContext = BaseContext & {
 
     http?: {
         /**
-         * The original HTTP request information.
+         * The original HTTP request.
          */
-        req?: RequestInfo;
+        req?: globalThis.Request;
 
         /**
          * Closes the SSE stream for this request, triggering client reconnection.
@@ -392,7 +391,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
 
     /**
      * Builds the context object for request handlers. Subclasses must override
-     * to return the appropriate context type (e.g., ServerContext adds requestInfo).
+     * to return the appropriate context type (e.g., ServerContext adds HTTP request info).
      */
     protected abstract buildContext(ctx: BaseContext, transportInfo?: MessageExtraInfo): ContextT;
 
diff --git a/packages/core/src/shared/transport.ts b/packages/core/src/shared/transport.ts
@@ -110,9 +110,9 @@ export interface Transport {
     /**
      * Callback for when a message (request or response) is received over the connection.
      *
-     * Includes the {@linkcode MessageExtraInfo.requestInfo | requestInfo} and {@linkcode MessageExtraInfo.authInfo | authInfo} if the transport is authenticated.
+     * Includes the {@linkcode MessageExtraInfo.request | request} and {@linkcode MessageExtraInfo.authInfo | authInfo} if the transport is authenticated.
      *
-     * The {@linkcode MessageExtraInfo.requestInfo | requestInfo} can be used to get the original request information (headers, etc.)
+     * The {@linkcode MessageExtraInfo.request | request} can be used to get the original request information (headers, etc.)
      */
     onmessage?: (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined;
 
diff --git a/packages/core/src/types/types.ts b/packages/core/src/types/types.ts
@@ -513,24 +513,14 @@ export type ListChangedHandlers = {
     resources?: ListChangedOptions<Resource>;
 };
 
-/**
- * Information about the incoming request.
- */
-export interface RequestInfo {
-    /**
-     * The headers of the request.
-     */
-    headers: Headers;
-}
-
 /**
  * Extra information about a message.
  */
 export interface MessageExtraInfo {
     /**
-     * The request information.
+     * The original HTTP request.
      */
-    requestInfo?: RequestInfo;
+    request?: globalThis.Request;
 
     /**
      * The authentication information.
diff --git a/packages/middleware/node/test/streamableHttp.test.ts b/packages/middleware/node/test/streamableHttp.test.ts
@@ -396,7 +396,7 @@ describe('Zod v4', () => {
         /***
          * Test: Tool With Request Info
          */
-        it('should pass request info to tool callback', async () => {
+        it('should expose the full Request object to tool handlers', async () => {
             sessionId = await initializeServer();
 
             mcpServer.registerTool(
@@ -406,10 +406,11 @@ describe('Zod v4', () => {
                     inputSchema: z.object({ name: z.string().describe('Name to greet') })
                 },
                 async ({ name }, ctx): Promise<CallToolResult> => {
-                    // Convert Headers object to plain object for JSON serialization
-                    // Headers is a Web API class that doesn't serialize with JSON.stringify
+                    const req = ctx.http?.req;
                     const serializedRequestInfo = {
-                        headers: Object.fromEntries(ctx.http?.req?.headers ?? new Headers())
+                        headers: Object.fromEntries(req?.headers ?? new Headers()),
+                        url: req?.url,
+                        method: req?.method
                     };
                     return {
                         content: [
@@ -464,10 +465,58 @@ describe('Zod v4', () => {
                     'user-agent': expect.any(String),
                     'accept-encoding': expect.any(String),
                     'content-length': expect.any(String)
-                }
+                },
+                url: expect.stringContaining(baseUrl.pathname),
+                method: 'POST'
             });
         });
 
+        it('should expose query parameters via the Request object', async () => {
+            sessionId = await initializeServer();
+
+            mcpServer.registerTool(
+                'test-query-params',
+                {
+                    description: 'A tool that reads query params',
+                    inputSchema: z.object({})
+                },
+                async (_args, ctx): Promise<CallToolResult> => {
+                    const req = ctx.http?.req;
+                    const url = new URL(req!.url);
+                    const params = Object.fromEntries(url.searchParams);
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify(params) }]
+                    };
+                }
+            );
+
+            const toolCallMessage: JSONRPCMessage = {
+                jsonrpc: '2.0',
+                method: 'tools/call',
+                params: {
+                    name: 'test-query-params',
+                    arguments: {}
+                },
+                id: 'call-2'
+            };
+
+            // Send to a URL with query parameters
+            const urlWithParams = new URL(baseUrl.toString());
+            urlWithParams.searchParams.set('foo', 'bar');
+            urlWithParams.searchParams.set('debug', 'true');
+
+            const response = await sendPostRequest(urlWithParams, toolCallMessage, sessionId);
+            expect(response.status).toBe(200);
+
+            const text = await readSSEEvent(response);
+            const dataLine = text.split('\n').find(line => line.startsWith('data:'));
+            expect(dataLine).toBeDefined();
+
+            const eventData = JSON.parse(dataLine!.slice(5));
+            const queryParams = JSON.parse(eventData.result.content[0].text);
+            expect(queryParams).toEqual({ foo: 'bar', debug: 'true' });
+        });
+
         it('should reject requests without a valid session ID', async () => {
             const response = await sendPostRequest(baseUrl, TEST_MESSAGES.toolsList);
 
diff --git a/packages/server/src/server/server.ts b/packages/server/src/server/server.ts
@@ -155,8 +155,7 @@ export class Server extends Protocol<ServerContext> {
 
     protected override buildContext(ctx: BaseContext, transportInfo?: MessageExtraInfo): ServerContext {
         // Only create http when there's actual HTTP transport info or auth info
-        const hasHttpInfo =
-            ctx.http || transportInfo?.requestInfo || transportInfo?.closeSSEStream || transportInfo?.closeStandaloneSSEStream;
+        const hasHttpInfo = ctx.http || transportInfo?.request || transportInfo?.closeSSEStream || transportInfo?.closeStandaloneSSEStream;
         return {
             ...ctx,
             mcpReq: {
@@ -168,7 +167,7 @@ export class Server extends Protocol<ServerContext> {
             http: hasHttpInfo
                 ? {
                       ...ctx.http,
-                      req: transportInfo?.requestInfo,
+                      req: transportInfo?.request,
                       closeSSE: transportInfo?.closeSSEStream,
                       closeStandaloneSSE: transportInfo?.closeStandaloneSSEStream
                   }
diff --git a/packages/server/src/server/streamableHttp.ts b/packages/server/src/server/streamableHttp.ts
@@ -7,7 +7,7 @@
  * For Node.js Express/HTTP compatibility, use {@linkcode @modelcontextprotocol/node!NodeStreamableHTTPServerTransport | NodeStreamableHTTPServerTransport} which wraps this transport.
  */
 
-import type { AuthInfo, JSONRPCMessage, MessageExtraInfo, RequestId, RequestInfo, Transport } from '@modelcontextprotocol/core';
+import type { AuthInfo, JSONRPCMessage, MessageExtraInfo, RequestId, Transport } from '@modelcontextprotocol/core';
 import {
     DEFAULT_NEGOTIATED_PROTOCOL_VERSION,
     isInitializeRequest,
@@ -634,10 +634,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                 return this.createJsonErrorResponse(415, -32_000, 'Unsupported Media Type: Content-Type must be application/json');
             }
 
-            // Build request info from headers
-            const requestInfo: RequestInfo = {
-                headers: req.headers
-            };
+            const request = req;
 
             let rawMessage;
             if (options?.parsedBody === undefined) {
@@ -707,7 +704,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
             if (!hasRequests) {
                 // if it only contains notifications or responses, return 202
                 for (const message of messages) {
-                    this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo });
+                    this.onmessage?.(message, { authInfo: options?.authInfo, request });
                 }
                 return new Response(null, { status: 202 });
             }
@@ -741,7 +738,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                     }
 
                     for (const message of messages) {
-                        this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo });
+                        this.onmessage?.(message, { authInfo: options?.authInfo, request });
                     }
                 });
             }
@@ -811,7 +808,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {
                     };
                 }
 
-                this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo, closeSSEStream, closeStandaloneSSEStream });
+                this.onmessage?.(message, { authInfo: options?.authInfo, request, closeSSEStream, closeStandaloneSSEStream });
             }
             // The server SHOULD NOT close the SSE stream before sending all JSON-RPC responses
             // This will be handled by the send() method when responses are ready

Original file line number	Diff line number	Diff line change
`@@ -110,9 +110,9 @@ export interface Transport {`
`110`	`110`	`/**`
`111`	`111`	`* Callback for when a message (request or response) is received over the connection.`
`112`	`112`	`*`
`113`		`- * Includes the {@linkcode MessageExtraInfo.requestInfo \| requestInfo} and {@linkcode MessageExtraInfo.authInfo \| authInfo} if the transport is authenticated.`
	`113`	`+ * Includes the {@linkcode MessageExtraInfo.request \| request} and {@linkcode MessageExtraInfo.authInfo \| authInfo} if the transport is authenticated.`
`114`	`114`	`*`
`115`		`- * The {@linkcode MessageExtraInfo.requestInfo \| requestInfo} can be used to get the original request information (headers, etc.)`
	`115`	`+ * The {@linkcode MessageExtraInfo.request \| request} can be used to get the original request information (headers, etc.)`
`116`	`116`	`*/`
`117`	`117`	`onmessage?: (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) \| undefined;`
`118`	`118`
Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`* For Node.js Express/HTTP compatibility, use {@linkcode @modelcontextprotocol/node!NodeStreamableHTTPServerTransport \| NodeStreamableHTTPServerTransport} which wraps this transport.`
`8`	`8`	`*/`
`9`	`9`
`10`		`-import type { AuthInfo, JSONRPCMessage, MessageExtraInfo, RequestId, RequestInfo, Transport } from '@modelcontextprotocol/core';`
	`10`	`+import type { AuthInfo, JSONRPCMessage, MessageExtraInfo, RequestId, Transport } from '@modelcontextprotocol/core';`
`11`	`11`	`import {`
`12`	`12`	`DEFAULT_NEGOTIATED_PROTOCOL_VERSION,`
`13`	`13`	`isInitializeRequest,`
`@@ -634,10 +634,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {`
`634`	`634`	`return this.createJsonErrorResponse(415, -32_000, 'Unsupported Media Type: Content-Type must be application/json');`
`635`	`635`	`}`
`636`	`636`
`637`		`- // Build request info from headers`
`638`		`- const requestInfo: RequestInfo = {`
`639`		`- headers: req.headers`
`640`		`- };`
	`637`	`+ const request = req;`
`641`	`638`
`642`	`639`	`let rawMessage;`
`643`	`640`	`if (options?.parsedBody === undefined) {`
`@@ -707,7 +704,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {`
`707`	`704`	`if (!hasRequests) {`
`708`	`705`	`// if it only contains notifications or responses, return 202`
`709`	`706`	`for (const message of messages) {`
`710`		`- this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo });`
	`707`	`+ this.onmessage?.(message, { authInfo: options?.authInfo, request });`
`711`	`708`	`}`
`712`	`709`	`return new Response(null, { status: 202 });`
`713`	`710`	`}`
`@@ -741,7 +738,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {`
`741`	`738`	`}`
`742`	`739`
`743`	`740`	`for (const message of messages) {`
`744`		`- this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo });`
	`741`	`+ this.onmessage?.(message, { authInfo: options?.authInfo, request });`
`745`	`742`	`}`
`746`	`743`	`});`
`747`	`744`	`}`
`@@ -811,7 +808,7 @@ export class WebStandardStreamableHTTPServerTransport implements Transport {`
`811`	`808`	`};`
`812`	`809`	`}`
`813`	`810`
`814`		`- this.onmessage?.(message, { authInfo: options?.authInfo, requestInfo, closeSSEStream, closeStandaloneSSEStream });`
	`811`	`+ this.onmessage?.(message, { authInfo: options?.authInfo, request, closeSSEStream, closeStandaloneSSEStream });`
`815`	`812`	`}`
`816`	`813`	`// The server SHOULD NOT close the SSE stream before sending all JSON-RPC responses`
`817`	`814`	`// This will be handled by the send() method when responses are ready`