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;
-    /** @deprecated For spec methods, pass the method string instead. */
+    public override setRequestHandler<P extends StandardSchemaV1>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ClientContext) => Result | Promise<Result>
+    ): void;
+    /** @deprecated For spec methods, pass the method string instead; for custom methods, prefer the 3-arg form. */
     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

packages/core/src/shared/protocol.ts

@@ -48,6 +48,8 @@ import type { ZodLikeRequestSchema } from '../util/compatSchema.js';
 import { extractMethodLiteral, isZodLikeSchema } from '../util/compatSchema.js';
 import type { AnySchema, SchemaOutput } from '../util/schema.js';
 import { parseSchema } from '../util/schema.js';
+import type { StandardSchemaV1 } from '../util/standardSchema.js';
+import { parseStandardSchema } from '../util/standardSchema.js';
 import type { TaskContext, TaskManagerHost, TaskManagerOptions, TaskRequestOptions } from './taskManager.js';
 import { NullTaskManager, TaskManager } from './taskManager.js';
 import type { Transport, TransportSendOptions } from './transport.js';
@@ -1020,26 +1022,72 @@ export abstract class Protocol<ContextT extends BaseContext> {
      * method. Replaces any previous handler for the same method.
      *
      * Call forms:
-     * - **Spec method** — `setRequestHandler('tools/call', (request, ctx) => …)`.
+     * - **Spec method, two args** — `setRequestHandler('tools/call', (request, ctx) => …)`.
      *   The full `RequestTypeMap[M]` request object is validated by the SDK and passed to the
      *   handler. This is the form `Client`/`Server` use and override.
+     * - **Three args** — `setRequestHandler('vendor/custom', paramsSchema, (params, ctx) => …)`.
+     *   Any method string; the supplied schema validates incoming `params`. Absent or undefined
+     *   `params` are normalized to `{}` (after stripping `_meta`) before validation, so for
+     *   no-params methods use `z.object({})`. `paramsSchema` may be any Standard Schema (Zod,
+     *   Valibot, ArkType, etc.).
      * - **Zod schema** — `setRequestHandler(RequestZodSchema, (request, ctx) => …)`. The method
      *   name is read from the schema's `method` literal; the handler receives the parsed request.
      */
     setRequestHandler<M extends RequestMethod>(
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ContextT) => Result | Promise<Result>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    setRequestHandler<P extends StandardSchemaV1>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>, ctx: ContextT) => Result | Promise<Result>
+    ): void;
+    /** @deprecated For spec methods, pass the method string instead; for custom methods, prefer the 3-arg form. */
     setRequestHandler<T extends ZodLikeRequestSchema>(
         requestSchema: T,
         handler: (request: ReturnType<T['parse']>, ctx: ContextT) => Result | Promise<Result>
     ): void;
-    setRequestHandler(method: string | ZodLikeRequestSchema, handler: (request: Request, ctx: ContextT) => Result | Promise<Result>): void {
+    setRequestHandler(
+        method: string | ZodLikeRequestSchema,
+        schemaOrHandler: StandardSchemaV1 | ((request: Request, ctx: ContextT) => Result | Promise<Result>),
+        maybeHandler?: (params: unknown, ctx: ContextT) => unknown
+    ): void {
         if (isZodLikeSchema(method)) {
-            return this._registerCompatRequestHandler(method, handler as (request: unknown, ctx: ContextT) => Result | Promise<Result>);
+            return this._registerCompatRequestHandler(
+                method,
+                schemaOrHandler as (request: unknown, ctx: ContextT) => Result | Promise<Result>
+            );
+        }
+        if (maybeHandler === undefined) {
+            return this._setRequestHandlerByMethod(
+                method,
+                schemaOrHandler as (request: Request, ctx: ContextT) => Result | Promise<Result>
+            );
         }
-        this._setRequestHandlerByMethod(method, handler);
+
+        this._setRequestHandlerByMethod(method, this._wrapParamsSchemaHandler(method, schemaOrHandler as StandardSchemaV1, maybeHandler));
+    }
+
+    /**
+     * Builds a request handler from a `paramsSchema` + params-only user handler. Strips `_meta`,
+     * validates `params` against the schema, and invokes the user handler with the parsed params.
+     * Shared by {@linkcode setRequestHandler}'s 3-arg dispatch and `Client`/`Server` overrides
+     * so that per-method wrapping can be applied uniformly to the normalized handler.
+     */
+    protected _wrapParamsSchemaHandler(
+        method: string,
+        paramsSchema: StandardSchemaV1,
+        userHandler: (params: unknown, ctx: ContextT) => unknown
+    ): (request: Request, ctx: ContextT) => Promise<Result> {
+        return async (request, ctx) => {
+            const { _meta, ...userParams } = (request.params ?? {}) as Record<string, unknown>;
+            void _meta;
+            const parsed = await parseStandardSchema(paramsSchema, userParams);
+            if (!parsed.success) {
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
+            }
+            return userHandler(parsed.data, ctx) as Result;
+        };
     }
 
     /**
@@ -1089,31 +1137,55 @@ export abstract class Protocol<ContextT extends BaseContext> {
      * Registers a handler to invoke when this protocol object receives a notification with the
      * given method. Replaces any previous handler for the same method.
      *
-     * Mirrors {@linkcode setRequestHandler}: a spec-method form (handler receives the full
-     * notification object) and a Zod-schema form (method read from the schema's `method` literal).
+     * Mirrors {@linkcode setRequestHandler}: a two-arg spec-method form (handler receives the full
+     * notification object), a three-arg form with a `paramsSchema` (handler receives validated
+     * `params`), and a Zod-schema form (method read from the schema's `method` literal).
      */
     setNotificationHandler<M extends NotificationMethod>(
         method: M,
         handler: (notification: NotificationTypeMap[M]) => void | Promise<void>
     ): void;
-    /** @deprecated For spec methods, pass the method string instead. */
+    setNotificationHandler<P extends StandardSchemaV1>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: StandardSchemaV1.InferOutput<P>) => void | Promise<void>
+    ): void;
+    /** @deprecated For spec methods, pass the method string instead; for custom methods, prefer the 3-arg form. */
     setNotificationHandler<T extends ZodLikeRequestSchema>(
         notificationSchema: T,
         handler: (notification: ReturnType<T['parse']>) => void | Promise<void>
     ): void;
-    setNotificationHandler(method: string | ZodLikeRequestSchema, handler: (notification: Notification) => void | Promise<void>): void {
+    setNotificationHandler(
+        method: string | ZodLikeRequestSchema,
+        schemaOrHandler: StandardSchemaV1 | ((notification: Notification) => void | Promise<void>),
+        maybeHandler?: (params: unknown) => void | Promise<void>
+    ): void {
         if (isZodLikeSchema(method)) {
             const notificationSchema = method;
             const methodStr = extractMethodLiteral(notificationSchema);
-            this._notificationHandlers.set(methodStr, n =>
-                Promise.resolve((handler as (n: unknown) => void | Promise<void>)(notificationSchema.parse(n)))
-            );
+            const handler = schemaOrHandler as (notification: unknown) => void | Promise<void>;
+            this._notificationHandlers.set(methodStr, n => Promise.resolve(handler(notificationSchema.parse(n))));
             return;
         }
-        const schema = getNotificationSchema(method as NotificationMethod);
-        this._notificationHandlers.set(method, notification => {
-            const parsed = schema ? schema.parse(notification) : notification;
-            return Promise.resolve(handler(parsed));
+        if (maybeHandler === undefined) {
+            const handler = schemaOrHandler as (notification: Notification) => void | Promise<void>;
+            const schema = getNotificationSchema(method as NotificationMethod);
+            this._notificationHandlers.set(method, notification => {
+                const parsed = schema ? schema.parse(notification) : notification;
+                return Promise.resolve(handler(parsed));
+            });
+            return;
+        }
+
+        const paramsSchema = schemaOrHandler as StandardSchemaV1;
+        this._notificationHandlers.set(method, async notification => {
+            const { _meta, ...userParams } = (notification.params ?? {}) as Record<string, unknown>;
+            void _meta;
+            const parsed = await parseStandardSchema(paramsSchema, userParams);
+            if (!parsed.success) {
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
+            }
+            return maybeHandler(parsed.data);
         });
     }