feat: support Standard JSON Schema (StandardJSONSchemaV1) for tool/prompt schemas

[mattzcarey]

Summary

Replace the Zod-specific AnySchema type with StandardJSONSchemaV1 from the Standard Schema spec for user-provided tool and prompt schemas. This enables any schema library that implements the spec (Zod v4, Valibot, ArkType, etc.) to be used for tool/prompt schemas.

Motivation and Context

Currently, the MCP SDK is tightly coupled to Zod for user-provided schemas. This PR makes the SDK library-agnostic by using the Standard Schema spec interfaces:

• StandardJSONSchemaV1: Primary interface - uses ~standard.jsonSchema.input/output() for JSON Schema conversion (wire protocol)
• StandardSchemaV1: Optional interface - uses ~standard.validate() for native validation when available

Libraries that implement these interfaces:

• Zod v4 - implements both (native validation + JSON Schema)
• Valibot - via @valibot/to-json-schema (native validation + JSON Schema)
• ArkType - implements both (native validation + JSON Schema)

Changes

Core (packages/core)

• New file: src/util/standardSchema.ts - Standard Schema interfaces and utilities
  • Type guards: isStandardJSONSchema(), isStandardSchema(), isStandardSchemaWithJSON()
  • JSON Schema conversion: standardSchemaToJsonSchema()
  • Validation: validateStandardSchema() (uses native validation if available, otherwise JSON Schema)
  • Prompt argument extraction: promptArgumentsFromStandardSchema()
• Updated src/util/schema.ts - Internal Zod utilities for protocol handling (unchanged API)
• Updated src/shared/protocol.ts - Use schema utility aliases instead of direct Zod imports

Server (packages/server)

• Updated src/server/mcp.ts
  • RegisteredTool.inputSchema/outputSchema now accept StandardJSONSchemaV1
  • RegisteredPrompt.argsSchema now accepts StandardJSONSchemaV1
  • Tool/prompt callbacks use StandardJSONSchemaV1.InferOutput<T> for type inference
  • Validation uses validateStandardSchema() for native validation when available

Client (packages/client)

• Updated src/client/client.ts - Use parseSchema utility instead of direct z.safeParse

Examples

• New: examples/server/src/arktypeExample.ts - ArkType schema example
• New: examples/server/src/valibotExample.ts - Valibot schema example

Tests

• New: test/integration/test/standardSchema.test.ts - Comprehensive integration tests
  • ArkType tool registration and validation
  • Valibot tool registration and validation
  • Mixed schema libraries in same server
  • Error message quality verification
  • Type inference verification

How Has This Been Tested?

1. All 377 existing tests pass - No regressions
2. New integration tests for ArkType and Valibot schemas
3. Manual testing of example servers with invalid input

Error Message Quality

All libraries produce clear, user-friendly error messages:

Library	Example Error
ArkType	age must be a number (was a string)
Valibot	Invalid type: Expected string but received 123
Zod	Invalid input: expected string, received number

Breaking Changes

• Tool/prompt inputSchema, outputSchema, and argsSchema now expect StandardJSONSchemaV1 instead of Zod's AnySchema
• Zod v4 schemas still work unchanged - Zod v4 implements StandardJSONSchemaV1
• The completable() function for prompt argument completion remains Zod-specific

API Examples

Zod (existing, unchanged)

import*aszfrom'zod/v4';server.registerTool('greet',{inputSchema: z.object({name: z.string()})},async({ name })=>{// name: string (type inference works)return{content: [{type: 'text',text: `Hello, ${name}!`}]};});

ArkType (new)

import{type}from'arktype';server.registerTool('greet',{inputSchema: type({name: 'string'})},async({ name })=>{return{content: [{type: 'text',text: `Hello, ${name}!`}]};});

Valibot (new)

import*asvfrom'valibot';import{toStandardJsonSchema}from'@valibot/to-json-schema';server.registerTool('greet',{inputSchema: toStandardJsonSchema(v.object({name: v.string()}))},async({ name })=>{return{content: [{type: 'text',text: `Hello, ${name}!`}]};});

Types of changes

• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[changeset-bot]

⚠️ No Changeset found

Latest commit: cb1e1ef

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1473

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1473

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1473

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1473

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1473

commit: cb1e1ef

[felixweinberger]

why the change to unknown?

[felixweinberger]

One thought for a potential follow-up: now that the SDK is moving to schema-library-agnostic types, the completable() API could be simplified to decouple it from Zod entirely.

Instead of embedding completion callbacks inside schema objects (which requires Zod-specific introspection to extract), completers could be passed explicitly in the prompt config:

server.registerPrompt('greeting',{argsSchema: type({name: 'string',language: 'string'}),// any librarycompleters: {name: (value)=>['Alice','Bob'].filter(n=>n.startsWith(value)),language: (value)=>['en','fr'].filter(l=>l.startsWith(value))}},callback);

The type simplifies too, since completion values are always strings over the wire:

typeCompleteCallback=(value: string,context?: {arguments?: Record<string,string>})=>string[]|Promise<string[]>;

This PR already does most of the internal plumbing — RegisteredPrompt stores completers?: Map<string, CompleteCallback>. The remaining step would be accepting them in the config directly, which would let us deprecate completable(), extractCompleters, and the Zod-specific helpers (getZodSchemaShape, unwrapZodOptionalSchema, etc.).

Not suggesting this as a blocker for this PR — just flagging as a natural follow-up that would complete the schema-agnostic story.

[felixweinberger]

Superseded by #1689