feat(core): 3-arg setRequestHandler/setNotificationHandler and request()/mcpReq.send schema overloads for custom methods

Author: felixweinberger

.changeset/custom-methods-minimal.md

@@ -0,0 +1,8 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Add custom (non-spec) method support: a 3-arg `setRequestHandler(method, schemas, handler)` / `setNotificationHandler(method, schemas, handler)` form for vendor-prefixed methods, and a `request(req, resultSchema)` overload (also on `ctx.mcpReq.send`) for typed custom-method results. Spec-method calls are unchanged.
+
+Response result-schema validation failure now rejects with `ProtocolError(InternalError)` instead of a raw `ZodError`.

docs/migration-SKILL.md

@@ -352,6 +352,26 @@ server.setRequestHandler('initialize', async (request) => { ... });
 server.setNotificationHandler('notifications/message', (notification) => { ... });
 ```
 
+For custom (non-spec) methods, use the 3-arg form `(method, schemas, handler)`:
+
+```typescript
+// v1: Zod schema with method literal
+server.setRequestHandler(z.object({ method: z.literal('acme/search'), params: P }), async req => { ... });
+
+// v2: method string + schemas object; handler receives parsed params
+server.setRequestHandler('acme/search', { params: P, result: R }, async (params, ctx) => { ... });
+client.setNotificationHandler('acme/progress', { params: P }, params => { ... });
+```
+
+To send a custom-method request, pass a result schema as the second argument to `request()` (and `ctx.mcpReq.send()`):
+
+```typescript
+// v1
+await client.request({ method: 'acme/search', params }, ResultSchema);
+// v2 (unchanged; now any Standard Schema, not Zod-only)
+await client.request({ method: 'acme/search', params }, ResultSchema);
+```
+
 Schema to method string mapping:
 
 | v1 Schema                               | v2 Method String                         |
@@ -407,9 +427,9 @@ Request/notification params remain fully typed. Remove unused schema imports aft
 | `ctx.mcpReq.elicitInput(params, options?)`     | Elicit user input (form or URL)                        | `server.elicitInput(...)` from within handler        |
 | `ctx.mcpReq.requestSampling(params, options?)` | Request LLM sampling from client                       | `server.createMessage(...)` from within handler      |
 
-## 11. Schema parameter removed from `request()`, `send()`, and `callTool()`
+## 11. Schema parameter removed from `request()`, `send()`, and `callTool()` (spec methods)
 
-`Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` no longer take a Zod result schema argument. The SDK resolves the schema internally from the method name.
+For **spec** methods, `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` no longer require a Zod result schema argument. The SDK resolves the schema internally from the method name.
 
 ```typescript
 // v1: schema required
@@ -433,6 +453,8 @@ const tool = await client.callTool({ name: 'my-tool', arguments: {} });
 | `client.callTool(params, CompatibilityCallToolResultSchema)` | `client.callTool(params)`          |
 | `client.callTool(params, schema, options)`                   | `client.callTool(params, options)` |
 
+For **custom (non-spec)** methods, keep the result-schema argument — see §9. Only apply the rewrites above when `req.method` is a spec method.
+
 Remove unused schema imports: `CallToolResultSchema`, `CompatibilityCallToolResultSchema`, `ElicitResultSchema`, `CreateMessageResultSchema`, etc., when they were only used in `request()`/`send()`/`callTool()` calls.
 
 If `CallToolResultSchema` was used for **runtime validation** (not just as a `request()` argument), replace with the `isCallToolResult` type guard:

docs/migration.md

@@ -364,6 +364,46 @@ server.setNotificationHandler('notifications/message', notification => {
 
 The request and notification parameters remain fully typed via `RequestTypeMap` and `NotificationTypeMap`. You no longer need to import the individual `*RequestSchema` or `*NotificationSchema` constants for handler registration.
 
+#### Custom (non-spec) methods
+
+For vendor-prefixed methods (anything not in the MCP spec), use the 3-arg form: pass the method string, a `{ params, result? }` schemas object, and the handler. Any [Standard Schema](https://standardschema.dev) library works (Zod, Valibot, ArkType).
+
+**Before (v1):**
+
+```typescript
+const AcmeSearch = z.object({
+    method: z.literal('acme/search'),
+    params: z.object({ query: z.string(), limit: z.number().int() })
+});
+server.setRequestHandler(AcmeSearch, async request => {
+    return { items: [/* ... */] };
+});
+```
+
+**After (v2):**
+
+```typescript
+const SearchParams = z.object({ query: z.string(), limit: z.number().int() });
+const SearchResult = z.object({ items: z.array(z.string()) });
+
+server.setRequestHandler('acme/search', { params: SearchParams, result: SearchResult }, async (params, ctx) => {
+    return { items: [/* ... */] };
+});
+```
+
+The handler receives the parsed `params` directly (not the full request envelope). `_meta` is stripped before validation and is available as `ctx.mcpReq._meta`. Supplying `result` types the handler's return value; omit it to return any `Result`.
+
+#### Sending custom-method requests
+
+`request()` and `ctx.mcpReq.send()` accept a result schema as the second argument; for custom methods this is required:
+
+```typescript
+const result = await client.request({ method: 'acme/search', params: { query: 'mcp', limit: 3 } }, SearchResult);
+result.items; // string[]
+```
+
+For spec methods the 1-arg form still works and the result type is inferred from the method name.
+
 Common method string replacements:
 
 | Schema (v1)                             | Method string (v2)                       |
@@ -382,10 +422,10 @@ Common method string replacements:
 | `ResourceListChangedNotificationSchema` | `'notifications/resources/list_changed'` |
 | `PromptListChangedNotificationSchema`   | `'notifications/prompts/list_changed'`   |
 
-### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
+### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer require a schema parameter for spec methods
 
-The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer accept a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas
-like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
+For **spec** methods, the public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods no longer require a Zod result schema argument. The SDK now resolves the correct result schema internally based on the method name. This means you no longer need to import result schemas
+like `CallToolResultSchema` or `ElicitResultSchema` when making spec-method requests.
 
 **`client.request()` — Before (v1):**
 
@@ -442,6 +482,8 @@ const result = await client.callTool({ name: 'my-tool', arguments: {} });
 
 The return type is now inferred from the method name via `ResultTypeMap`. For example, `client.request({ method: 'tools/call', ... })` returns `Promise<CallToolResult | CreateTaskResult>`.
 
+For **custom (non-spec)** methods, keep the result-schema argument — see [Sending custom-method requests](#sending-custom-method-requests). Only drop the schema when calling a spec method.
+
 If you were using `CallToolResultSchema` for **runtime validation** (not just in `request()`/`callTool()` calls), use the new `isCallToolResult` type guard instead:
 
 ```typescript

examples/client/src/customMethodExample.ts

@@ -0,0 +1,24 @@
+/**
+ * Custom (non-spec) method example: a client that sends `acme/search` and
+ * listens for `acme/searchProgress` notifications.
+ *
+ * Run after starting `examples/server/src/customMethodExample.ts`.
+ */
+import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
+import { z } from 'zod/v4';
+
+const SearchResult = z.object({ items: z.array(z.string()) });
+const SearchProgressParams = z.object({ stage: z.string(), pct: z.number() });
+
+const client = new Client({ name: 'acme-search-client', version: '0.0.0' });
+
+client.setNotificationHandler('acme/searchProgress', { params: SearchProgressParams }, params => {
+    console.log(`[progress] ${params.stage} ${Math.round(params.pct * 100)}%`);
+});
+
+await client.connect(new StdioClientTransport({ command: 'node', args: ['../server/dist/customMethodExample.js'] }));
+
+const result = await client.request({ method: 'acme/search', params: { query: 'mcp', limit: 3 } }, SearchResult);
+console.log('items:', result.items);
+
+await client.close();

examples/server/src/customMethodExample.ts

@@ -0,0 +1,22 @@
+/**
+ * Custom (non-spec) method example: a server that handles a vendor-prefixed
+ * `acme/search` request and emits `acme/searchProgress` notifications.
+ *
+ * Run alongside `examples/client/src/customMethodExample.ts`.
+ */
+import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { z } from 'zod/v4';
+
+const SearchParams = z.object({ query: z.string(), limit: z.number().int().default(10) });
+const SearchResult = z.object({ items: z.array(z.string()) });
+
+const mcp = new McpServer({ name: 'acme-search', version: '0.0.0' });
+
+mcp.server.setRequestHandler('acme/search', { params: SearchParams, result: SearchResult }, async (params, ctx) => {
+    await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'start', pct: 0 } });
+    const items = Array.from({ length: params.limit }, (_, i) => `${params.query}-${i}`);
+    await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'done', pct: 1 } });
+    return { items };
+});
+
+await mcp.connect(new StdioServerTransport());

packages/client/src/client/client.ts

@@ -24,7 +24,6 @@ import type {
     NotificationMethod,
     ProtocolOptions,
     ReadResourceRequest,
-    RequestMethod,
     RequestOptions,
     Result,
     ServerCapabilities,
@@ -570,7 +569,7 @@ export class Client extends Protocol<ClientContext> {
         return this._instructions;
     }
 
-    protected assertCapabilityForMethod(method: RequestMethod): void {
+    protected assertCapabilityForMethod(method: string): void {
         switch (method as ClientRequest['method']) {
             case 'logging/setLevel': {
                 if (!this._serverCapabilities?.logging) {
@@ -633,7 +632,7 @@ export class Client extends Protocol<ClientContext> {
         }
     }
 
-    protected assertNotificationCapability(method: NotificationMethod): void {
+    protected assertNotificationCapability(method: string): void {
         switch (method as ClientNotification['method']) {
             case 'notifications/roots/list_changed': {
                 if (!this._capabilities.roots?.listChanged) {

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

@@ -45,6 +45,7 @@ export type {
     NotificationOptions,
     ProgressCallback,
     ProtocolOptions,
+    RequestHandlerSchemas,
     RequestOptions,
     ServerContext
 } from '../../shared/protocol.js';

packages/core/src/shared/protocol.examples.ts

@@ -0,0 +1,29 @@
+/**
+ * Type-checked examples for `protocol.ts`.
+ *
+ * These examples are synced into JSDoc comments via the sync-snippets script.
+ * Each function's region markers define the code snippet that appears in the docs.
+ *
+ * @module
+ */
+
+import * as z from 'zod/v4';
+
+import type { BaseContext, Protocol } from './protocol.js';
+
+/**
+ * Example: registering a handler for a custom (non-spec) request method.
+ */
+function Protocol_setRequestHandler_customMethod(protocol: Protocol<BaseContext>) {
+    //#region Protocol_setRequestHandler_customMethod
+    const SearchParams = z.object({ query: z.string(), limit: z.number().optional() });
+    const SearchResult = z.object({ hits: z.array(z.string()) });
+
+    protocol.setRequestHandler('acme/search', { params: SearchParams, result: SearchResult }, async (params, _ctx) => {
+        return { hits: [`result for ${params.query}`] };
+    });
+    //#endregion Protocol_setRequestHandler_customMethod
+    void protocol;
+}
+
+void Protocol_setRequestHandler_customMethod;