feat(core): 3-arg setRequestHandler/setNotificationHandler with validator-agnostic paramsSchema

Adds the three-arg form: setRequestHandler('vendor/method', paramsSchema, (params, ctx) => …),
where paramsSchema is any Standard Schema (Zod, Valibot, ArkType, etc.). Handler receives
validated params; absent params normalize to {} (after stripping _meta). Same for
setNotificationHandler.

Ergonomic alternative to writing a full Zod request schema with method literal.

Author: felixweinberger

.changeset/three-arg-custom-methods.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+`setRequestHandler`/`setNotificationHandler` gain a 3-arg `(method: string, paramsSchema, handler)` form for custom (non-spec) methods. `paramsSchema` is any Standard Schema (Zod, Valibot, ArkType, etc.); the handler receives validated `params`.

docs/migration-SKILL.md

@@ -377,14 +377,16 @@ Schema to method string mapping:
 
 Request/notification params remain fully typed. Remove unused schema imports after migration.
 
-**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — work on `Client`/`Server` directly using the same v1 Zod-schema form:
-
-| Form                                                         | Notes                                                                 |
-| ------------------------------------------------------------ | --------------------------------------------------------------------- |
-| `setRequestHandler(CustomReqSchema, (req, ctx) => ...)`      | unchanged                                                             |
-| `setNotificationHandler(CustomNotifSchema, n => ...)`        | unchanged                                                             |
-| `this.request({ method: 'vendor/x', params }, ResultSchema)` | unchanged                                                             |
-| `this.notification({ method: 'vendor/x', params })`          | unchanged                                                             |
+**Custom (non-standard) methods** — vendor extensions or sub-protocols whose method strings are not in the MCP spec — work on `Client`/`Server` directly. The v1 Zod-schema forms continue to work; the three-arg `(method, paramsSchema, handler)` form is the alternative:
+
+| v1 (still supported)                                         | v2 alternative                                                           |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `setRequestHandler(CustomReqSchema, (req, ctx) => ...)`      | `setRequestHandler('vendor/method', ParamsSchema, (params, ctx) => ...)` |
+| `setNotificationHandler(CustomNotifSchema, n => ...)`        | `setNotificationHandler('vendor/method', ParamsSchema, params => ...)`   |
+| `this.request({ method: 'vendor/x', params }, ResultSchema)` | unchanged                                                                |
+| `this.notification({ method: 'vendor/x', params })`          | unchanged                                                                |
+
+For the three-arg form, the v1 schema's `.shape.params` becomes the `ParamsSchema` argument and the `method: z.literal('...')` value becomes the string argument.
 
 ## 10. Request Handler Context Types
 

docs/migration.md

@@ -384,15 +384,19 @@ Common method string replacements:
 
 ### Custom (non-standard) protocol methods
 
-Vendor-specific methods are registered directly on `Client` or `Server` using the same Zod-schema form as v1: `setRequestHandler(zodSchemaWithMethodLiteral, handler)`. `request({ method, params }, ResultSchema)` and `notification({ method, params })` are unchanged from v1.
+Vendor-specific methods are registered directly on `Client` or `Server`. The v1 form `setRequestHandler(zodSchemaWithMethodLiteral, handler)` continues to work; the three-arg `(methodString, paramsSchema, handler)` form is the v2 alternative. `request({ method, params }, ResultSchema)` and `notification({ method, params })` are unchanged from v1.
 
 ```typescript
 import { Server } from '@modelcontextprotocol/server';
 
 const server = new Server({ name: 'app', version: '1.0.0' }, { capabilities: {} });
 
+// v1 form (still supported):
 server.setRequestHandler(SearchRequestSchema, req => ({ hits: [req.params.query] }));
 
+// v2 alternative — pass method string + params schema; handler receives validated params:
+server.setRequestHandler('acme/search', SearchParams, params => ({ hits: [params.query] }));
+
 // Calling from a Client — unchanged from v1:
 const result = await client.request({ method: 'acme/search', params: { query: 'x' } }, SearchResult);
 ```

examples/client/src/customMethodExample.ts

@@ -3,8 +3,11 @@
  * Calling vendor-specific (non-spec) JSON-RPC methods from a `Client`.
  *
  * - Send a custom request: `client.request({ method, params }, resultSchema)`
- * - Send a custom notification: `client.notification({ method, params })`
- * - Receive a custom notification: `client.setNotificationHandler(ZodSchemaWithMethodLiteral, handler)`
+ * - Send a custom notification: `client.notification({ method, params })` (unchanged from v1)
+ * - Receive a custom notification: 3-arg `client.setNotificationHandler(method, paramsSchema, handler)`
+ *
+ * These overloads are on `Client` and `Server` directly — you do NOT need a raw
+ * `Protocol` instance for custom methods.
  *
  * Pair with the server in examples/server/src/customMethodExample.ts.
  */
@@ -13,16 +16,12 @@ import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
 import { z } from 'zod';
 
 const SearchResult = z.object({ hits: z.array(z.string()) });
-
-const ProgressNotification = z.object({
-    method: z.literal('acme/searchProgress'),
-    params: z.object({ stage: z.string(), pct: z.number() })
-});
+const ProgressParams = z.object({ stage: z.string(), pct: z.number() });
 
 const client = new Client({ name: 'custom-method-client', version: '1.0.0' }, { capabilities: {} });
 
-client.setNotificationHandler(ProgressNotification, n => {
-    console.log(`[client] progress: ${n.params.stage} ${n.params.pct}%`);
+client.setNotificationHandler('acme/searchProgress', ProgressParams, p => {
+    console.log(`[client] progress: ${p.stage} ${p.pct}%`);
 });
 
 await client.connect(new StdioClientTransport({ command: 'node', args: ['../server/dist/customMethodExample.js'] }));

examples/server/src/customMethodExample.ts

@@ -2,9 +2,10 @@
 /**
  * Registering vendor-specific (non-spec) JSON-RPC methods on a `Server`.
  *
- * Custom methods use the Zod-schema form of `setRequestHandler` / `setNotificationHandler`:
- * pass a Zod object schema whose `method` field is `z.literal('<method>')`. The same overload
- * is available on `Client` (for server→client custom methods).
+ * Custom methods use the 3-arg form of `setRequestHandler` / `setNotificationHandler`:
+ * pass the method string, a params schema, and the handler. The same overload is
+ * available on `Client` (for server→client custom methods) — you do NOT need a raw
+ * `Protocol` instance for this.
  *
  * To call these from the client side, use:
  *   await client.request({ method: 'acme/search', params: { query: 'widgets' } }, SearchResult)
@@ -15,28 +16,21 @@
 import { Server, StdioServerTransport } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
-const SearchRequest = z.object({
-    method: z.literal('acme/search'),
-    params: z.object({ query: z.string() })
-});
-
-const TickNotification = z.object({
-    method: z.literal('acme/tick'),
-    params: z.object({ n: z.number() })
-});
+const SearchParams = z.object({ query: z.string() });
+const TickParams = z.object({ n: z.number() });
 
 const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
 
-server.setRequestHandler(SearchRequest, async (request, ctx) => {
-    console.log('[server] acme/search query=' + request.params.query);
+server.setRequestHandler('acme/search', SearchParams, async (params, ctx) => {
+    console.log('[server] acme/search query=' + params.query);
     await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'start', pct: 0 } });
-    const hits = [request.params.query, request.params.query + '-result'];
+    const hits = [params.query, params.query + '-result'];
     await ctx.mcpReq.notify({ method: 'acme/searchProgress', params: { stage: 'done', pct: 100 } });
     return { hits };
 });
 
-server.setNotificationHandler(TickNotification, n => {
-    console.log('[server] acme/tick n=' + n.params.n);
+server.setNotificationHandler('acme/tick', TickParams, p => {
+    console.log('[server] acme/tick n=' + p.n);
 });
 
 await server.connect(new StdioServerTransport());

packages/client/src/client/client.ts

@@ -32,6 +32,7 @@ import type {
     Result,
     ResultTypeMap,
     ServerCapabilities,
+    StandardSchemaV1,
     SubscribeRequest,
     TaskManagerOptions,
     Tool,
@@ -343,22 +344,34 @@ export class Client extends Protocol<ClientContext> {
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
     ): void;
+    public override setRequestHandler<P extends StandardSchemaV1>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ClientContext) => Result | Promise<Result>
+    ): void;
     /** For spec methods the method-string form is more concise; this overload is the supported call form for non-spec methods or when you want full-envelope validation. */
     public override setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ClientContext) => Result | Promise<Result>
     ): void;
-    public override setRequestHandler(methodOrSchema: string | ZodLikeRequestSchema, schemaHandler: unknown): void {
+    public override setRequestHandler(
+        methodOrSchema: string | ZodLikeRequestSchema,
+        schemaOrHandler: unknown,
+        maybeHandler?: (params: unknown, ctx: ClientContext) => unknown
+    ): void {
         let method: string;
         let handler: (request: Request, ctx: ClientContext) => ClientResult | Promise<ClientResult>;
         if (isZodLikeSchema(methodOrSchema)) {
             const schema = methodOrSchema;
-            const userHandler = schemaHandler as (request: unknown, ctx: ClientContext) => Result | Promise<Result>;
+            const userHandler = schemaOrHandler as (request: unknown, ctx: ClientContext) => Result | Promise<Result>;
             method = extractMethodLiteral(schema);
             handler = (req, ctx) => userHandler(schema.parse(req), ctx);
+        } else if (maybeHandler === undefined) {
+            method = methodOrSchema;
+            handler = schemaOrHandler as (request: Request, ctx: ClientContext) => ClientResult | Promise<ClientResult>;
         } else {
             method = methodOrSchema;
-            handler = schemaHandler as (request: Request, ctx: ClientContext) => ClientResult | Promise<ClientResult>;
+            handler = this._wrapParamsSchemaHandler(method, schemaOrHandler as StandardSchemaV1, maybeHandler);
         }
         if (method === 'elicitation/create') {
             const wrappedHandler = async (request: Request, ctx: ClientContext): Promise<ClientResult> => {

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

@@ -137,7 +137,7 @@ export { isTerminal } from '../../experimental/tasks/interfaces.js';
 export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
 
 // Validator types and classes
-export type { StandardSchemaWithJSON } from '../../util/standardSchema.js';
+export type { StandardSchemaV1, StandardSchemaWithJSON } from '../../util/standardSchema.js';
 export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';
 export type { CfWorkerSchemaDraft } from '../../validators/cfWorkerProvider.js';
 // fromJsonSchema is intentionally NOT exported here — the server and client packages