feat(core): custom-method overloads on setRequestHandler/setNotificationHandler/request; export Protocol + ProtocolSpec for typed custom vocabularies

Adds to Protocol (inherited by Client/Server):
- 3-arg setRequestHandler/setNotificationHandler(method: string, paramsSchema, handler) for custom methods (validator-agnostic)
- setRequestHandler/setNotificationHandler(ZodSchema, handler) — v1 form, first-class
- request(req, resultSchema) — v1 form, first-class
- Method-keyed request() return: request({method:M}) returns ResultTypeMap[M]
- ProtocolSpec generic Protocol<ContextT, SpecT = McpSpec> with typed-vocabulary overloads for subclassers

Protocol stays abstract; now exported (was reachable in v1 via deep imports).

Author: felixweinberger

.changeset/custom-method-overloads.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+`setRequestHandler`/`setNotificationHandler` gain a 3-arg `(method: string, paramsSchema, handler)` form for non-spec methods, and accept the v1 `(ZodSchema, handler)` form as a first-class alternative. `request()` gains a string-form `(method, params, resultSchema)` overload and a method-keyed return type for the object form. `callTool(params, resultSchema?)` accepts the v1 schema arg (ignored). `Protocol` gains a reserved second generic `SpecT extends ProtocolSpec = McpSpec` for typed custom-method vocabularies; the class remains abstract.

.changeset/deprecate-helper.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/core': patch
+---
+
+Add internal `deprecate()` warn-once helper for v1-compat shims.

docs/migration-SKILL.md

@@ -377,6 +377,19 @@ 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. 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, extra) => ...)`    | `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                                                                      |
+| `class X extends Protocol<Req, Notif, Res>`                  | `class X extends Client` (or `Server`), or compose a `Client` instance         |
+
+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
 
 `RequestHandlerExtra` → structured context types with nested groups. Rename `extra` → `ctx` in all handler callbacks.

docs/migration.md

@@ -382,9 +382,30 @@ 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`. 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);
+```
+
+If you previously subclassed `Protocol<SendRequestT, SendNotificationT, SendResultT>` for a custom dialect, extend `Client` or `Server` instead (or compose one). `Protocol` remains abstract and is not exported.
+
+### `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,35 @@
+#!/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 })` (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.
+ */
+
+import { Client, StdioClientTransport } from '@modelcontextprotocol/client';
+import { z } from 'zod';
+
+const SearchResult = z.object({ hits: z.array(z.string()) });
+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('acme/searchProgress', ProgressParams, p => {
+    console.log(`[client] progress: ${p.stage} ${p.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,33 @@
+#!/usr/bin/env node
+/**
+ * Registering vendor-specific (non-spec) JSON-RPC methods on a `Server`.
+ *
+ * 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)
+ *   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 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('acme/search', SearchParams, params => {
+    console.log('[server] acme/search query=' + params.query);
+    return { hits: [params.query, params.query + '-result'] };
+});
+
+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

@@ -1,7 +1,9 @@
 import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/client/_shims';
 import type {
+    AnySchema,
     BaseContext,
     CallToolRequest,
+    CallToolResult,
     ClientCapabilities,
     ClientContext,
     ClientNotification,
@@ -24,16 +26,20 @@ import type {
     NotificationMethod,
     ProtocolOptions,
     ReadResourceRequest,
+    Request,
     RequestMethod,
     RequestOptions,
     RequestTypeMap,
+    Result,
     ResultTypeMap,
+    SchemaOutput,
     ServerCapabilities,
     SubscribeRequest,
     TaskManagerOptions,
     Tool,
     Transport,
-    UnsubscribeRequest
+    UnsubscribeRequest,
+    ZodLikeRequestSchema
 } from '@modelcontextprotocol/core';
 import {
     assertClientRequestTaskCapability,
@@ -50,6 +56,7 @@ import {
     extractTaskManagerOptions,
     GetPromptResultSchema,
     InitializeResultSchema,
+    isZodLikeSchema,
     LATEST_PROTOCOL_VERSION,
     ListChangedOptionsBaseSchema,
     ListPromptsResultSchema,
@@ -336,9 +343,37 @@ 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;
+    public override setRequestHandler<P extends AnySchema>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: SchemaOutput<P>, ctx: ClientContext) => Result | Promise<Result>
+    ): 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,
+        schemaOrHandler: unknown,
+        maybeHandler?: (params: unknown, ctx: ClientContext) => unknown
     ): void {
+        if (isZodLikeSchema(method)) {
+            return this._registerCompatRequestHandler(
+                method,
+                schemaOrHandler as (request: unknown, ctx: ClientContext) => Result | Promise<Result>
+            );
+        }
+        if (maybeHandler !== undefined) {
+            return super.setRequestHandler(
+                method,
+                schemaOrHandler as AnySchema,
+                maybeHandler as (params: unknown, ctx: ClientContext) => Result | Promise<Result>
+            );
+        }
+        const handler = schemaOrHandler 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 +439,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 +482,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 +902,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(
@@ -1011,7 +1057,7 @@ export class Client extends Protocol<ClientContext> {
         options: ListChangedOptions<T>,
         fetcher: () => Promise<T[]>
     ): void {
-        // Validate options using Zod schema (validates autoRefresh and debounceMs)
+        // Validate options (autoRefresh and debounceMs)
         const parseResult = parseSchema(ListChangedOptionsBaseSchema, options);
         if (!parseResult.success) {
             throw new Error(`Invalid ${listType} listChanged options: ${parseResult.error.message}`);

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

@@ -4,9 +4,8 @@
  * This module defines the stable, public-facing API surface. Client and server
  * packages re-export from here so that end users only see supported symbols.
  *
- * Internal utilities (Protocol class, stdio parsing, schema helpers, etc.)
- * remain available via the internal barrel (@modelcontextprotocol/core) for
- * use by client/server packages.
+ * Internal utilities (mergeCapabilities, schema helpers, etc.) remain available
+ * via the internal barrel (@modelcontextprotocol/core) for use by client/server packages.
  */
 
 // Auth error classes
@@ -38,7 +37,13 @@ export { checkResourceAllowed, resourceUrlFromServerUrl } from '../../shared/aut
 // Metadata utilities
 export { getDisplayName } from '../../shared/metadataUtils.js';
 
-// Protocol types (NOT the Protocol class itself or mergeCapabilities)
+// Protocol class (abstract — subclass for custom vocabularies) + ProtocolSpec types. NOT mergeCapabilities.
+export type { McpSpec, ProtocolSpec, SpecNotifications, SpecRequests } from '../../shared/protocol.js';
+export { Protocol } from '../../shared/protocol.js';
+export type { ZodLikeRequestSchema } from '../../util/compatSchema.js';
+export { InMemoryTransport } from '../../util/inMemory.js';
+export type { AnySchema, SchemaOutput } from '../../util/schema.js';
+// Protocol types
 export type {
     BaseContext,
     ClientContext,