feat(core): restore v1 Zod-schema overloads on setRequestHandler/setNotificationHandler/request

Adds to Protocol (inherited by Client/Server):
- setRequestHandler/setNotificationHandler(ZodSchema, handler) — the v1 form, first-class
- request(req, resultSchema, opts?) — the v1 explicit-schema form, first-class
- callTool(params, resultSchema?, opts?) — accepts the v1 schema arg (ignored) for source compat
- removeRequestHandler/removeNotificationHandler/assertCanSetRequestHandler accept any method string

Custom (non-spec) methods work via the Zod-schema form, same as v1.
schema.ts/standardSchema.ts unchanged from main.

Author: felixweinberger

.changeset/custom-method-overloads.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+`setRequestHandler`/`setNotificationHandler` accept the v1 `(ZodSchema, handler)` form as a first-class alternative to `(methodString, handler)`. `request()` accepts an explicit result schema (`request(req, resultSchema, options?)`) and has a method-keyed return type for spec methods. `callTool(params, resultSchema?)` accepts the v1 schema arg (ignored). `removeRequestHandler`/`removeNotificationHandler`/`assertCanSetRequestHandler` accept any method string.

docs/migration-SKILL.md

@@ -377,6 +377,15 @@ 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                                                             |
+
 ## 10. Request Handler Context Types
 
 `RequestHandlerExtra` → structured context types with nested groups. Rename `extra` → `ctx` in all handler callbacks.

docs/migration.md

@@ -382,9 +382,24 @@ 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
+### Custom (non-standard) protocol 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
+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.
+
+```typescript
+import { Server } from '@modelcontextprotocol/server';
+
+const server = new Server({ name: 'app', version: '1.0.0' }, { capabilities: {} });
+
+server.setRequestHandler(SearchRequestSchema, req => ({ hits: [req.params.query] }));
+
+// Calling from a Client — unchanged from v1:
+const result = await client.request({ method: 'acme/search', params: { query: 'x' } }, SearchResult);
+```
+
+### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` schema parameter is now optional
+
+The public `Protocol.request()`, `BaseContext.mcpReq.send()`, and `Client.callTool()` methods still accept a result schema argument, but for spec methods it is optional — the SDK resolves the correct schema internally from the method name. You no longer need to import result schemas
 like `CallToolResultSchema` or `ElicitResultSchema` when making requests.
 
 **`client.request()` — Before (v1):**

examples/client/README.md

@@ -36,6 +36,7 @@ Most clients expect a server to be running. Start one from [`../server/README.md
 | Client credentials (M2M)                            | Machine-to-machine OAuth client credentials example.                                      | [`src/simpleClientCredentials.ts`](src/simpleClientCredentials.ts)                         |
 | URL elicitation client                              | Drives URL-mode elicitation flows (sensitive input in a browser).                         | [`src/elicitationUrlExample.ts`](src/elicitationUrlExample.ts)                             |
 | Task interactive client                             | Demonstrates task-based execution + interactive server→client requests.                   | [`src/simpleTaskInteractiveClient.ts`](src/simpleTaskInteractiveClient.ts)                 |
+| Custom (non-standard) methods client                | Sends `acme/*` custom requests and handles custom server notifications.                   | [`src/customMethodExample.ts`](src/customMethodExample.ts)                                 |
 
 ## URL elicitation example (server + client)
 

examples/client/src/customMethodExample.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * 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)`
+ *
+ * Pair with the server in examples/server/src/customMethodExample.ts.
+ */
+
+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 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}%`);
+});
+
+await client.connect(new StdioClientTransport({ command: 'node', args: ['../server/dist/customMethodExample.js'] }));
+
+const r = await client.request({ method: 'acme/search', params: { query: 'widgets' } }, SearchResult);
+console.log('[client] hits=' + JSON.stringify(r.hits));
+
+await client.notification({ method: 'acme/tick', params: { n: 1 } });
+await client.notification({ method: 'acme/tick', params: { n: 2 } });
+
+await client.close();

examples/server/README.md

@@ -38,6 +38,7 @@ pnpm tsx src/simpleStreamableHttp.ts
 | Task interactive server                   | Task-based execution with interactive server→client requests.                                   | [`src/simpleTaskInteractive.ts`](src/simpleTaskInteractive.ts)                           |
 | Hono Streamable HTTP server               | Streamable HTTP server built with Hono instead of Express.                                      | [`src/honoWebStandardStreamableHttp.ts`](src/honoWebStandardStreamableHttp.ts)           |
 | SSE polling demo server                   | Legacy SSE server intended for polling demos.                                                   | [`src/ssePollingExample.ts`](src/ssePollingExample.ts)                                   |
+| Custom (non-standard) methods server      | Registers `acme/*` custom request handlers and sends custom notifications.                      | [`src/customMethodExample.ts`](src/customMethodExample.ts)                               |
 
 ## OAuth demo flags (Streamable HTTP server)
 

examples/server/src/customMethodExample.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+/**
+ * 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).
+ *
+ * To call these from the client side, use:
+ *   await client.request({ method: 'acme/search', params: { query: 'widgets' } }, SearchResult)
+ *   await client.notification({ method: 'acme/tick', params: { n: 1 } })
+ * See examples/client/src/customMethodExample.ts.
+ */
+
+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 server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
+
+server.setRequestHandler(SearchRequest, request => {
+    console.log('[server] acme/search query=' + request.params.query);
+    return { hits: [request.params.query, request.params.query + '-result'] };
+});
+
+server.setNotificationHandler(TickNotification, n => {
+    console.log('[server] acme/tick n=' + n.params.n);
+});
+
+await server.connect(new StdioServerTransport());

packages/client/src/client/client.ts

@@ -2,6 +2,7 @@ import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/client/_shims'
 import type {
     BaseContext,
     CallToolRequest,
+    CallToolResult,
     ClientCapabilities,
     ClientContext,
     ClientNotification,
@@ -24,16 +25,19 @@ import type {
     NotificationMethod,
     ProtocolOptions,
     ReadResourceRequest,
+    Request,
     RequestMethod,
     RequestOptions,
     RequestTypeMap,
+    Result,
     ResultTypeMap,
     ServerCapabilities,
     SubscribeRequest,
     TaskManagerOptions,
     Tool,
     Transport,
-    UnsubscribeRequest
+    UnsubscribeRequest,
+    ZodLikeRequestSchema
 } from '@modelcontextprotocol/core';
 import {
     assertClientRequestTaskCapability,
@@ -50,6 +54,7 @@ import {
     extractTaskManagerOptions,
     GetPromptResultSchema,
     InitializeResultSchema,
+    isZodLikeSchema,
     LATEST_PROTOCOL_VERSION,
     ListChangedOptionsBaseSchema,
     ListPromptsResultSchema,
@@ -336,9 +341,21 @@ export class Client extends Protocol<ClientContext> {
     public override setRequestHandler<M extends RequestMethod>(
         method: M,
         handler: (request: RequestTypeMap[M], ctx: ClientContext) => ResultTypeMap[M] | Promise<ResultTypeMap[M]>
-    ): void {
+    ): void;
+    public override setRequestHandler<T extends ZodLikeRequestSchema>(
+        requestSchema: T,
+        handler: (request: ReturnType<T['parse']>, ctx: ClientContext) => Result | Promise<Result>
+    ): void;
+    public override setRequestHandler(method: string | ZodLikeRequestSchema, schemaHandler: unknown): void {
+        if (isZodLikeSchema(method)) {
+            return this._registerCompatRequestHandler(
+                method,
+                schemaHandler as (request: unknown, ctx: ClientContext) => Result | Promise<Result>
+            );
+        }
+        const handler = schemaHandler as (request: Request, ctx: ClientContext) => ClientResult | Promise<ClientResult>;
         if (method === 'elicitation/create') {
-            const wrappedHandler = async (request: RequestTypeMap[M], ctx: ClientContext): Promise<ClientResult> => {
+            const wrappedHandler = async (request: Request, ctx: ClientContext): Promise<ClientResult> => {
                 const validatedRequest = parseSchema(ElicitRequestSchema, request);
                 if (!validatedRequest.success) {
                     // Type guard: if success is false, error is guaranteed to exist
@@ -404,11 +421,11 @@ export class Client extends Protocol<ClientContext> {
             };
 
             // Install the wrapped handler
-            return super.setRequestHandler(method, wrappedHandler);
+            return super.setRequestHandler(method as RequestMethod, wrappedHandler);
         }
 
         if (method === 'sampling/createMessage') {
-            const wrappedHandler = async (request: RequestTypeMap[M], ctx: ClientContext): Promise<ClientResult> => {
+            const wrappedHandler = async (request: Request, ctx: ClientContext): Promise<ClientResult> => {
                 const validatedRequest = parseSchema(CreateMessageRequestSchema, request);
                 if (!validatedRequest.success) {
                     const errorMessage =
@@ -447,11 +464,11 @@ export class Client extends Protocol<ClientContext> {
             };
 
             // Install the wrapped handler
-            return super.setRequestHandler(method, wrappedHandler);
+            return super.setRequestHandler(method as RequestMethod, wrappedHandler);
         }
 
         // Other handlers use default behavior
-        return super.setRequestHandler(method, handler);
+        return super.setRequestHandler(method as RequestMethod, handler);
     }
 
     protected assertCapability(capability: keyof ServerCapabilities, method: string): void {
@@ -867,7 +884,18 @@ export class Client extends Protocol<ClientContext> {
      * }
      * ```
      */
-    async callTool(params: CallToolRequest['params'], options?: RequestOptions) {
+    async callTool(params: CallToolRequest['params'], options?: RequestOptions): Promise<CallToolResult>;
+    /** Result schema is resolved automatically; the second argument is accepted for v1 source compatibility and ignored. */
+    async callTool(params: CallToolRequest['params'], resultSchema: unknown, options?: RequestOptions): Promise<CallToolResult>;
+    async callTool(
+        params: CallToolRequest['params'],
+        optionsOrSchema?: RequestOptions | unknown,
+        maybeOptions?: RequestOptions
+    ): Promise<CallToolResult> {
+        const options: RequestOptions | undefined =
+            optionsOrSchema && typeof optionsOrSchema === 'object' && 'parse' in optionsOrSchema
+                ? maybeOptions
+                : (optionsOrSchema as RequestOptions | undefined);
         // Guard: required-task tools need experimental API
         if (this.isToolTaskRequired(params.name)) {
             throw new ProtocolError(

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

@@ -49,6 +49,7 @@ export type {
     ServerContext
 } from '../../shared/protocol.js';
 export { DEFAULT_REQUEST_TIMEOUT_MSEC } from '../../shared/protocol.js';
+export type { ZodLikeRequestSchema } from '../../util/compatSchema.js';
 
 // Task manager types (NOT TaskManager class itself — internal)
 export type { RequestTaskStore, TaskContext, TaskManagerOptions, TaskRequestOptions } from '../../shared/taskManager.js';

packages/core/src/index.ts

@@ -48,4 +48,6 @@ export * from './validators/fromJsonSchema.js';
  */
 
 // Core types only - implementations are exported via separate entry points
+export type { ZodLikeRequestSchema } from './util/compatSchema.js';
+export { extractMethodLiteral, isZodLikeSchema } from './util/compatSchema.js';
 export type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './validators/types.js';