feat(core): accept StandardSchemaV1 in setCustom*/sendCustom* (not just Zod)

AnySchema is now StandardSchemaV1 (which Zod schemas implement), and parseSchema
routes through validateStandardSchema. This lets specTypeSchema() output and other
non-Zod Standard Schemas be passed directly to setCustomRequestHandler /
setCustomNotificationHandler / sendCustomRequest / sendCustomNotification.

parseSchema is now async; all 16 callers were already in async contexts except
_setupListChangedHandler, which is now async too (called from connect()).
validateStandardSchema constraint relaxed from StandardSchemaWithJSON to
StandardSchemaV1. isSchemaBundle was already StandardSchema-aware.

Author: felixweinberger

packages/client/src/client/client.ts

@@ -255,23 +255,23 @@ export class Client extends Protocol<ClientContext> {
      * Handlers are silently skipped if the server doesn't advertise the corresponding listChanged capability.
      * @internal
      */
-    private _setupListChangedHandlers(config: ListChangedHandlers): void {
+    private async _setupListChangedHandlers(config: ListChangedHandlers): Promise<void> {
         if (config.tools && this._serverCapabilities?.tools?.listChanged) {
-            this._setupListChangedHandler('tools', 'notifications/tools/list_changed', config.tools, async () => {
+            await this._setupListChangedHandler('tools', 'notifications/tools/list_changed', config.tools, async () => {
                 const result = await this.listTools();
                 return result.tools;
             });
         }
 
         if (config.prompts && this._serverCapabilities?.prompts?.listChanged) {
-            this._setupListChangedHandler('prompts', 'notifications/prompts/list_changed', config.prompts, async () => {
+            await this._setupListChangedHandler('prompts', 'notifications/prompts/list_changed', config.prompts, async () => {
                 const result = await this.listPrompts();
                 return result.prompts;
             });
         }
 
         if (config.resources && this._serverCapabilities?.resources?.listChanged) {
-            this._setupListChangedHandler('resources', 'notifications/resources/list_changed', config.resources, async () => {
+            await this._setupListChangedHandler('resources', 'notifications/resources/list_changed', config.resources, async () => {
                 const result = await this.listResources();
                 return result.resources;
             });
@@ -339,7 +339,7 @@ export class Client extends Protocol<ClientContext> {
     ): void {
         if (method === 'elicitation/create') {
             const wrappedHandler = async (request: RequestTypeMap[M], ctx: ClientContext): Promise<ClientResult> => {
-                const validatedRequest = parseSchema(ElicitRequestSchema, request);
+                const validatedRequest = await parseSchema(ElicitRequestSchema, request);
                 if (!validatedRequest.success) {
                     // Type guard: if success is false, error is guaranteed to exist
                     const errorMessage =
@@ -363,7 +363,7 @@ export class Client extends Protocol<ClientContext> {
 
                 // When task creation is requested, validate and return CreateTaskResult
                 if (params.task) {
-                    const taskValidationResult = parseSchema(CreateTaskResultSchema, result);
+                    const taskValidationResult = await parseSchema(CreateTaskResultSchema, result);
                     if (!taskValidationResult.success) {
                         const errorMessage =
                             taskValidationResult.error instanceof Error
@@ -375,7 +375,7 @@ export class Client extends Protocol<ClientContext> {
                 }
 
                 // For non-task requests, validate against ElicitResultSchema
-                const validationResult = parseSchema(ElicitResultSchema, result);
+                const validationResult = await parseSchema(ElicitResultSchema, result);
                 if (!validationResult.success) {
                     // Type guard: if success is false, error is guaranteed to exist
                     const errorMessage =
@@ -409,7 +409,7 @@ export class Client extends Protocol<ClientContext> {
 
         if (method === 'sampling/createMessage') {
             const wrappedHandler = async (request: RequestTypeMap[M], ctx: ClientContext): Promise<ClientResult> => {
-                const validatedRequest = parseSchema(CreateMessageRequestSchema, request);
+                const validatedRequest = await parseSchema(CreateMessageRequestSchema, request);
                 if (!validatedRequest.success) {
                     const errorMessage =
                         validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
@@ -422,7 +422,7 @@ export class Client extends Protocol<ClientContext> {
 
                 // When task creation is requested, validate and return CreateTaskResult
                 if (params.task) {
-                    const taskValidationResult = parseSchema(CreateTaskResultSchema, result);
+                    const taskValidationResult = await parseSchema(CreateTaskResultSchema, result);
                     if (!taskValidationResult.success) {
                         const errorMessage =
                             taskValidationResult.error instanceof Error
@@ -436,7 +436,7 @@ export class Client extends Protocol<ClientContext> {
                 // For non-task requests, validate against appropriate schema based on tools presence
                 const hasTools = params.tools || params.toolChoice;
                 const resultSchema = hasTools ? CreateMessageResultWithToolsSchema : CreateMessageResultSchema;
-                const validationResult = parseSchema(resultSchema, result);
+                const validationResult = await parseSchema(resultSchema, result);
                 if (!validationResult.success) {
                     const errorMessage =
                         validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
@@ -538,7 +538,7 @@ export class Client extends Protocol<ClientContext> {
 
             // Set up list changed handlers now that we know server capabilities
             if (this._pendingListChangedConfig) {
-                this._setupListChangedHandlers(this._pendingListChangedConfig);
+                await this._setupListChangedHandlers(this._pendingListChangedConfig);
                 this._pendingListChangedConfig = undefined;
             }
         } catch (error) {
@@ -1005,14 +1005,14 @@ export class Client extends Protocol<ClientContext> {
      * Set up a single list changed handler.
      * @internal
      */
-    private _setupListChangedHandler<T>(
+    private async _setupListChangedHandler<T>(
         listType: string,
         notificationMethod: NotificationMethod,
         options: ListChangedOptions<T>,
         fetcher: () => Promise<T[]>
-    ): void {
-        // Validate options using Zod schema (validates autoRefresh and debounceMs)
-        const parseResult = parseSchema(ListChangedOptionsBaseSchema, options);
+    ): Promise<void> {
+        // Validate options (autoRefresh and debounceMs)
+        const parseResult = await parseSchema(ListChangedOptionsBaseSchema, options);
         if (!parseResult.success) {
             throw new Error(`Invalid ${listType} listChanged options: ${parseResult.error.message}`);
         }

packages/core/src/shared/protocol.ts

@@ -867,7 +867,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
                 reject(error);
             };
 
-            this._responseHandlers.set(messageId, response => {
+            this._responseHandlers.set(messageId, async response => {
                 if (options?.signal?.aborted) {
                     return;
                 }
@@ -877,7 +877,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
                 }
 
                 try {
-                    const parseResult = parseSchema(resultSchema, response.result);
+                    const parseResult = await parseSchema(resultSchema, response.result);
                     if (parseResult.success) {
                         resolve(parseResult.data as SchemaOutput<T>);
                     } else {
@@ -1079,14 +1079,14 @@ export abstract class Protocol<ContextT extends BaseContext> {
         if (isRequestMethod(method)) {
             throw new Error(`"${method}" is a standard MCP request method. Use setRequestHandler() instead.`);
         }
-        this._requestHandlers.set(method, (request, ctx) => {
+        this._requestHandlers.set(method, async (request, ctx) => {
             const { _meta, ...userParams } = (request.params ?? {}) as Record<string, unknown>;
             void _meta;
-            const parsed = parseSchema(paramsSchema, userParams);
+            const parsed = await parseSchema(paramsSchema, userParams);
             if (!parsed.success) {
                 throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
             }
-            return Promise.resolve(handler(parsed.data, ctx));
+            return handler(parsed.data, ctx);
         });
     }
 
@@ -1119,14 +1119,14 @@ export abstract class Protocol<ContextT extends BaseContext> {
         if (isNotificationMethod(method)) {
             throw new Error(`"${method}" is a standard MCP notification method. Use setNotificationHandler() instead.`);
         }
-        this._notificationHandlers.set(method, notification => {
+        this._notificationHandlers.set(method, async notification => {
             const { _meta, ...userParams } = (notification.params ?? {}) as Record<string, unknown>;
             void _meta;
-            const parsed = parseSchema(paramsSchema, userParams);
+            const parsed = await parseSchema(paramsSchema, userParams);
             if (!parsed.success) {
                 throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
             }
-            return Promise.resolve(handler(parsed.data));
+            return handler(parsed.data);
         });
     }
 
@@ -1178,7 +1178,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
     ): Promise<unknown> {
         let resultSchema: AnySchema;
         if (isSchemaBundle(schemaOrBundle)) {
-            const parsed = parseSchema(schemaOrBundle.params, params);
+            const parsed = await parseSchema(schemaOrBundle.params, params);
             if (!parsed.success) {
                 throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
             }
@@ -1217,7 +1217,7 @@ export abstract class Protocol<ContextT extends BaseContext> {
     ): Promise<void> {
         let options: NotificationOptions | undefined;
         if (schemasOrOptions && 'params' in schemasOrOptions) {
-            const parsed = parseSchema(schemasOrOptions.params, params);
+            const parsed = await parseSchema(schemasOrOptions.params, params);
             if (!parsed.success) {
                 throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid params for ${method}: ${parsed.error.message}`);
             }

packages/core/src/util/schema.ts

@@ -1,32 +1,47 @@
 /**
- * Internal Zod schema utilities for protocol handling.
+ * Standard Schema utilities for protocol handling.
  * These are used internally by the SDK for protocol message validation.
  */
 
-import * as z from 'zod/v4';
+import type * as z from 'zod/v4';
+
+import type { StandardSchemaV1 } from './standardSchema.js';
+import { validateStandardSchema } from './standardSchema.js';
 
 /**
- * Base type for any Zod schema.
+ * Base type for any schema accepted by the SDK's user-facing schema parameters.
+ *
+ * This is the Standard Schema interface (https://standardschema.dev), which Zod, Valibot, ArkType
+ * and others implement. Zod schemas satisfy this constraint natively.
  */
-export type AnySchema = z.core.$ZodType;
+export type AnySchema = StandardSchemaV1;
 
 /**
  * A Zod schema for objects specifically.
+ *
+ * Retained for internal use where the SDK needs Zod-specific introspection (e.g. converting a tool
+ * input schema to JSON Schema). Not used for user-facing schema parameters.
  */
 export type AnyObjectSchema = z.core.$ZodObject;
 
 /**
- * Extracts the output type from a Zod schema.
+ * Extracts the output type from a Standard Schema.
  */
-export type SchemaOutput<T extends AnySchema> = z.output<T>;
+export type SchemaOutput<T extends AnySchema> = StandardSchemaV1.InferOutput<T>;
 
 /**
- * Parses data against a Zod schema (synchronous).
- * Returns a discriminated union with success/error.
+ * Parses data against a Standard Schema.
+ *
+ * Returns a discriminated union with success/error. The error is a plain `Error` whose `message`
+ * is a comma-separated list of issues, so callers can interpolate it directly.
  */
-export function parseSchema<T extends AnySchema>(
+export async function parseSchema<T extends AnySchema>(
     schema: T,
     data: unknown
-): { success: true; data: z.output<T> } | { success: false; error: z.core.$ZodError } {
-    return z.safeParse(schema, data);
+): Promise<{ success: true; data: SchemaOutput<T> } | { success: false; error: Error }> {
+    const result = await validateStandardSchema(schema, data);
+    if (result.success) {
+        return result;
+    }
+    return { success: false, error: new Error(result.error) };
 }

packages/core/src/util/standardSchema.ts

@@ -169,15 +169,15 @@ function formatIssue(issue: StandardSchemaV1.Issue): string {
     return `${path}: ${issue.message}`;
 }
 
-export async function validateStandardSchema<T extends StandardSchemaWithJSON>(
+export async function validateStandardSchema<T extends StandardSchemaV1>(
     schema: T,
     data: unknown
-): Promise<StandardSchemaValidationResult<StandardSchemaWithJSON.InferOutput<T>>> {
+): Promise<StandardSchemaValidationResult<StandardSchemaV1.InferOutput<T>>> {
     const result = await schema['~standard'].validate(data);
     if (result.issues && result.issues.length > 0) {
         return { success: false, error: result.issues.map(i => formatIssue(i)).join(', ') };
     }
-    return { success: true, data: (result as StandardSchemaV1.SuccessResult<unknown>).value as StandardSchemaWithJSON.InferOutput<T> };
+    return { success: true, data: (result as StandardSchemaV1.SuccessResult<unknown>).value as StandardSchemaV1.InferOutput<T> };
 }
 
 // Prompt argument extraction

packages/core/test/shared/customMethods.test.ts

@@ -6,6 +6,7 @@ import type { BaseContext } from '../../src/shared/protocol.js';
 import { Protocol } from '../../src/shared/protocol.js';
 import { ProtocolError, ProtocolErrorCode } from '../../src/types/index.js';
 import { InMemoryTransport } from '../../src/util/inMemory.js';
+import type { StandardSchemaV1 } from '../../src/util/standardSchema.js';
 
 class TestProtocol extends Protocol<BaseContext> {
     protected assertCapabilityForMethod(): void {}
@@ -273,3 +274,47 @@ describe('sendCustomNotification', () => {
         expect(count).toBe(1);
     });
 });
+
+describe('setCustom* — accepts non-Zod StandardSchemaV1', () => {
+    function makeStandardSchema<T>(validate: (v: unknown) => T | { issues: ReadonlyArray<{ message: string }> }): StandardSchemaV1<T> {
+        return {
+            '~standard': {
+                version: 1 as const,
+                vendor: 'test',
+                types: undefined as unknown as { input: T; output: T },
+                validate: (v: unknown) => {
+                    const r = validate(v);
+                    return typeof r === 'object' && r !== null && 'issues' in r ? r : { value: r as T };
+                }
+            }
+        };
+    }
+
+    test('setCustomRequestHandler validates via ~standard.validate (no Zod)', async () => {
+        const [client, server] = await linkedPair();
+
+        type Params = { n: number };
+        const ParamsSchema = makeStandardSchema<Params>(v =>
+            typeof v === 'object' && v !== null && typeof (v as Params).n === 'number'
+                ? (v as Params)
+                : { issues: [{ message: 'n must be a number' }] }
+        );
+        const ResultSchema = makeStandardSchema<{ doubled: number }>(v =>
+            typeof v === 'object' && v !== null && typeof (v as { doubled: number }).doubled === 'number'
+                ? (v as { doubled: number })
+                : { issues: [{ message: 'doubled must be a number' }] }
+        );
+
+        server.setCustomRequestHandler('test/double', ParamsSchema, async (params: Params) => ({ doubled: params.n * 2 }));
+
+        const result = await client.sendCustomRequest('test/double', { n: 21 }, ResultSchema);
+        expect(result.doubled).toBe(42);
+
+        await expect(client.sendCustomRequest('test/double', { n: 'nope' }, ResultSchema)).rejects.toSatisfy(
+            (e: unknown) => e instanceof ProtocolError && /n must be a number/.test(e.message)
+        );
+
+        await client.close();
+        await server.close();
+    });
+});

packages/server/src/server/server.ts

@@ -145,7 +145,7 @@ export class Server extends Protocol<ServerContext> {
             const transportSessionId: string | undefined =
                 ctx.sessionId || (ctx.http?.req?.headers.get('mcp-session-id') as string) || undefined;
             const { level } = request.params;
-            const parseResult = parseSchema(LoggingLevelSchema, level);
+            const parseResult = await parseSchema(LoggingLevelSchema, level);
             if (parseResult.success) {
                 this._loggingLevels.set(transportSessionId, parseResult.data);
             }
@@ -228,7 +228,7 @@ export class Server extends Protocol<ServerContext> {
     ): void {
         if (method === 'tools/call') {
             const wrappedHandler = async (request: RequestTypeMap[M], ctx: ServerContext): Promise<ServerResult> => {
-                const validatedRequest = parseSchema(CallToolRequestSchema, request);
+                const validatedRequest = await parseSchema(CallToolRequestSchema, request);
                 if (!validatedRequest.success) {
                     const errorMessage =
                         validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
@@ -241,7 +241,7 @@ export class Server extends Protocol<ServerContext> {
 
                 // When task creation is requested, validate and return CreateTaskResult
                 if (params.task) {
-                    const taskValidationResult = parseSchema(CreateTaskResultSchema, result);
+                    const taskValidationResult = await parseSchema(CreateTaskResultSchema, result);
                     if (!taskValidationResult.success) {
                         const errorMessage =
                             taskValidationResult.error instanceof Error
@@ -253,7 +253,7 @@ export class Server extends Protocol<ServerContext> {
                 }
 
                 // For non-task requests, validate against CallToolResultSchema
-                const validationResult = parseSchema(CallToolResultSchema, result);
+                const validationResult = await parseSchema(CallToolResultSchema, result);
                 if (!validationResult.success) {
                     const errorMessage =
                         validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);