feat(core): add custom request/notification handler API to Protocol

Adds setCustomRequestHandler, setCustomNotificationHandler, sendCustomRequest,
sendCustomNotification (plus remove* variants) to the Protocol class. These
allow registering handlers for vendor-specific methods outside the standard
RequestMethod/NotificationMethod unions, with user-provided Zod schemas for
param/result validation.

Custom handlers share the existing _requestHandlers map and dispatch path,
so they receive full context (cancellation, task support, send/notify) for
free. Capability checks are skipped for custom methods.

Also exports InMemoryTransport from core/public so examples and tests can
use createLinkedPair() without depending on the internal core barrel, and
adds examples/server/src/customMethodExample.ts demonstrating the API.

Author: felixweinberger

examples/server/package.json

@@ -33,6 +33,7 @@
     },
     "dependencies": {
         "@hono/node-server": "catalog:runtimeServerOnly",
+        "@modelcontextprotocol/client": "workspace:^",
         "@modelcontextprotocol/examples-shared": "workspace:^",
         "@modelcontextprotocol/express": "workspace:^",
         "@modelcontextprotocol/hono": "workspace:^",

examples/server/src/customMethodExample.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Demonstrates custom (non-standard) request and notification methods.
+ *
+ * The Protocol class exposes setCustomRequestHandler / setCustomNotificationHandler /
+ * sendCustomRequest / sendCustomNotification for vendor-specific methods that are not
+ * part of the MCP spec. Params and results are validated against user-provided Zod
+ * schemas, and handlers receive the same context (cancellation, task support,
+ * bidirectional send/notify) as standard handlers.
+ */
+
+import { Client } from '@modelcontextprotocol/client';
+import { InMemoryTransport, Server } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+
+const SearchParamsSchema = z.object({
+    query: z.string(),
+    limit: z.number().int().positive().optional()
+});
+
+const SearchResultSchema = z.object({
+    results: z.array(z.object({ id: z.string(), title: z.string() })),
+    total: z.number()
+});
+
+const AnalyticsParamsSchema = z.object({
+    event: z.string(),
+    properties: z.record(z.string(), z.unknown()).optional()
+});
+
+const AnalyticsResultSchema = z.object({ recorded: z.boolean() });
+
+const StatusUpdateParamsSchema = z.object({
+    status: z.enum(['idle', 'busy', 'error']),
+    detail: z.string().optional()
+});
+
+async function main() {
+    const server = new Server({ name: 'custom-method-server', version: '1.0.0' }, { capabilities: {} });
+    const client = new Client({ name: 'custom-method-client', version: '1.0.0' }, { capabilities: {} });
+
+    server.setCustomRequestHandler('acme/search', SearchParamsSchema, async (params, ctx) => {
+        console.log(`[server] acme/search query="${params.query}" limit=${params.limit ?? 'unset'} (req ${ctx.mcpReq.id})`);
+        return {
+            results: [
+                { id: 'r1', title: `Result for "${params.query}"` },
+                { id: 'r2', title: 'Another result' }
+            ],
+            total: 2
+        };
+    });
+
+    server.setCustomRequestHandler('acme/analytics', AnalyticsParamsSchema, async params => {
+        console.log(`[server] acme/analytics event="${params.event}"`);
+        return { recorded: true };
+    });
+
+    client.setCustomNotificationHandler('acme/statusUpdate', StatusUpdateParamsSchema, params => {
+        console.log(`[client] acme/statusUpdate status=${params.status} detail=${params.detail ?? '<none>'}`);
+    });
+
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+    const searchResult = await client.sendCustomRequest('acme/search', { query: 'widgets', limit: 5 }, SearchResultSchema);
+    console.log(`[client] received ${searchResult.total} results, first: "${searchResult.results[0]?.title}"`);
+
+    const analyticsResult = await client.sendCustomRequest('acme/analytics', { event: 'page_view' }, AnalyticsResultSchema);
+    console.log(`[client] analytics recorded=${analyticsResult.recorded}`);
+
+    await server.sendCustomNotification('acme/statusUpdate', { status: 'busy', detail: 'indexing' });
+
+    // Validation error: wrong param type (limit must be a number)
+    try {
+        await client.sendCustomRequest('acme/search', { query: 'widgets', limit: 'five' }, SearchResultSchema);
+        console.error('[client] expected validation error but request succeeded');
+    } catch (error) {
+        console.log(`[client] validation error (expected): ${(error as Error).message}`);
+    }
+
+    await client.close();
+    await server.close();
+}
+
+await main();

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

@@ -133,6 +133,9 @@ export type {
 export { isTerminal } from '../../experimental/tasks/interfaces.js';
 export { InMemoryTaskMessageQueue, InMemoryTaskStore } from '../../experimental/tasks/stores/inMemory.js';
 
+// Transport utilities
+export { InMemoryTransport } from '../../util/inMemory.js';
+
 // Validator types and classes
 export type { StandardSchemaWithJSON } from '../../util/standardSchema.js';
 export { AjvJsonSchemaValidator } from '../../validators/ajvProvider.js';

packages/core/src/shared/protocol.ts

@@ -1057,6 +1057,96 @@ export abstract class Protocol<ContextT extends BaseContext> {
     removeNotificationHandler(method: NotificationMethod): void {
         this._notificationHandlers.delete(method);
     }
+
+    /**
+     * Registers a handler for a custom (non-standard) request method.
+     *
+     * Unlike {@linkcode Protocol.setRequestHandler | setRequestHandler}, this accepts any method
+     * string and validates incoming params against a user-provided schema instead of an SDK-defined
+     * one. Capability checks are skipped. The handler receives the same {@linkcode BaseContext | context}
+     * as standard handlers, including cancellation, task support, and bidirectional send/notify.
+     */
+    setCustomRequestHandler<P extends AnySchema>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: SchemaOutput<P>, ctx: ContextT) => Result | Promise<Result>
+    ): void {
+        this._requestHandlers.set(method, (request, ctx) => {
+            const parsed = parseSchema(paramsSchema, request.params);
+            if (!parsed.success) {
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
+            }
+            return Promise.resolve(handler(parsed.data, ctx));
+        });
+    }
+
+    /**
+     * Removes a custom request handler previously registered with
+     * {@linkcode Protocol.setCustomRequestHandler | setCustomRequestHandler}.
+     */
+    removeCustomRequestHandler(method: string): void {
+        this._requestHandlers.delete(method);
+    }
+
+    /**
+     * Registers a handler for a custom (non-standard) notification method.
+     *
+     * Unlike {@linkcode Protocol.setNotificationHandler | setNotificationHandler}, this accepts any
+     * method string and validates incoming params against a user-provided schema instead of an
+     * SDK-defined one.
+     */
+    setCustomNotificationHandler<P extends AnySchema>(
+        method: string,
+        paramsSchema: P,
+        handler: (params: SchemaOutput<P>) => void | Promise<void>
+    ): void {
+        this._notificationHandlers.set(method, notification => {
+            const parsed = parseSchema(paramsSchema, notification.params);
+            if (!parsed.success) {
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
+            }
+            return Promise.resolve(handler(parsed.data));
+        });
+    }
+
+    /**
+     * Removes a custom notification handler previously registered with
+     * {@linkcode Protocol.setCustomNotificationHandler | setCustomNotificationHandler}.
+     */
+    removeCustomNotificationHandler(method: string): void {
+        this._notificationHandlers.delete(method);
+    }
+
+    /**
+     * Sends a custom (non-standard) request and waits for a response, validating the result against
+     * the provided schema.
+     *
+     * Unlike {@linkcode Protocol.request | request}, this accepts any method string. Capability
+     * checks are bypassed when {@linkcode ProtocolOptions.enforceStrictCapabilities} is disabled
+     * (the default).
+     */
+    sendCustomRequest<T extends AnySchema>(
+        method: string,
+        params: Record<string, unknown> | undefined,
+        resultSchema: T,
+        options?: RequestOptions
+    ): Promise<SchemaOutput<T>> {
+        return this._requestWithSchema({ method, params } as Request, resultSchema, options);
+    }
+
+    /**
+     * Sends a custom (non-standard) notification.
+     *
+     * Unlike {@linkcode Protocol.notification | notification}, this accepts any method string and
+     * bypasses capability checks by sending directly via the transport.
+     */
+    async sendCustomNotification(method: string, params?: Record<string, unknown>, options?: NotificationOptions): Promise<void> {
+        if (!this._transport) {
+            throw new SdkError(SdkErrorCode.NotConnected, 'Not connected');
+        }
+        const jsonrpcNotification: JSONRPCNotification = { jsonrpc: '2.0', method, params };
+        await this._transport.send(jsonrpcNotification, options);
+    }
 }
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {