feat: zod v4 with backwards compatibility for v3.25+ #1040

dclark27 · 2025-10-23T20:03:57Z

Add transparent Zod v3/v4 compatibility to the MCP TypeScript SDK, allowing users to install and use either version without any code changes or configuration. This addresses the need for the SDK to support multiple major versions of Zod in user applications.

The SDK exports v4 schemas by default, but the compatibility layer detects the Zod version at runtime and routes all schema operations (parsing, JSON Schema conversion, schema construction) to the appropriate implementation.

How Has This Been Tested?

Install the published version and test in your own app:

npm i @modelcontextprotocol/sdk

# or

pnpm i @modelcontextprotocol/sdk

Comprehensive Test Coverage

49 Test Suites | 1045 Tests (all passing)
User-facing APIs tested with both v3 and v4:
- Client core functionality (v3 + v4)
- Server core functionality (v3 + v4)
- MCP protocol handling (v3 + v4)
- All major transports: SSE, HTTP, stdio (v3 + v4)
- Completable schemas (v3 + v4)
- Client authentication (v3 + v4)
- Integration tests: task resumability, state management (v3 + v4)
Internal utilities tested with v4 only:
- OAuth schemas and utilities (internal SDK infrastructure)
- Shared protocol utilities

Test Files Created

9 .v3.test.ts files demonstrating real Zod v3 usage patterns
Tests import SDK schemas directly from types.js
Tests define custom schemas using their Zod version
Identical test logic between v3 and v4 versions

Breaking Changes

None. This is purely additive:

All v4 (default) behavior unchanged
No API modifications
No configuration required

Types of changes

New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally (1045/1045 passing)
I have added appropriate error handling (compat layer includes runtime guards)
I have added or updated documentation as needed (updated README.md)

Migration Path

Users can migrate from v3 to v4 at their own pace:

v3 users: Continue using zod@3 - everything works as before
v4 users: Use zod@4 or zod/v4 imports - get smaller bundle size and better performance
Mixed environments: Each schema shape must use a single version (enforced at runtime)

dclark27 · 2025-10-30T17:09:15Z

Update:

Merge conflicts resolved. 1.20.2-next.0 published under @socotra/modelcontextprotocol-sdk@next

Update 10/31:

Updated to 1.21.0 and released under @socotra/modelcontextprotocol-sdk

wladyslawczyzewski · 2025-10-31T17:28:03Z

any info when we should expect this PR to merge? 🤔

punkpeye · 2025-11-02T17:55:53Z

This PR cannot land soon enough.

colinhacks · 2025-11-04T23:42:01Z

cc @StefanTerdell

publishing a 3.25.x for zod-to-json-schema would go a long way here.

colinhacks · 2025-11-04T23:32:11Z

package.json

        "raw-body": "^3.0.0",
-        "zod": "^3.23.8",
-        "zod-to-json-schema": "^3.24.1"
+        "zod": "^3.25 || ^4.0"


For the Anthropic team: Zod 3.25 was a minor release with no breaking changes from Zod 3.24. It did however introduce a pre-release version of Zod 4 at the "zod/v4" subpath. It also added a re-export of Zod 3 from "zod/v3".

The idea is that these subpaths are "permalinks" to these associated versions that can be referenced by any library with a peer dependency on zod@>3.25.0 (including 4.x, and additional future majors beyond).

That's why this PR is using this pattern. The usage of Zod in this PR is idiomatic and consistent with the best practices described in my Library Authors writeup, which are already in use in the AI SDK, React Hook Form, and several others in the wild.

Thanks for taking time to review!

colinhacks · 2025-11-04T23:32:41Z

package.json

    "peerDependencies": {
-        "@cfworker/json-schema": "^4.1.1"
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"


This PR does bump the minimum version to 3.25.0, so any users fro Zod 3.23.x or 3.24.x would need to bump their version.

You could categorize this as a breaking change, but I personally think bumping a peer dep to a new minor version does not constitute a breaking change on your part. There were no breaking changes between Zod 3.23 -> 3.25 so it's a one-line npm command for users to upgrade.

There are also far more Zod 3.25 & Zod 4 users (52m/wk downlods) than Zod 3.24 users (6m/wk) or Zod 3.23 users (5m/wk). The upside of merging this is far greater than the downside to users who are pinned on older versions. Feel free to tag me if you receive any pushback on this and I'll explain why the bump was necessary.

Thanks for the additional explanation here - very helpful context to have these numbers.

I believe npm install would warn folks if they have an outdated peer dependency pinned, so it would at least not be a silent failure, so that's an additional mitigating factor. I'll also call this out in the release notes for this one.

trojanowski · 2025-11-06T20:19:17Z

src/_vendor/zod-to-json-schema/index.ts

Shouldn't these files actually be put into a subfolder, so that the full path would be src/vendor/zod-to-json-schema/? It would be problematic if we add another vendored library in the future.

dclark27 · 2025-11-11T23:01:06Z

Please tag me when ready for the merge conflicts to be resolved. The new work in #816 and #1086 makes resolving quite complex with the existing changes in here and I'd like to batch the fixes when you guys are ready to merge.

@KKonstantinov @pcarleton Please review as soon as possible. We have a very large backlog of folks waiting for this PR and we have the author of Zod providing feedback for us.

mattzcarey · 2025-11-17T11:11:21Z

Hey @dclark27. Thanks so much for your contribution and all this work. I want to get this merged and support this change. Could you help me understand the vendoring then I'd love if you could rebase and we can get this going.

Why are you vendoring the zod-to-json-schema lib? This sdk was using this lib directly before no? I'm guessing this would remove a whole class of bugs if so.

I have tested this in some of my own projects and it seems to work well :)

dclark27 · 2025-11-17T19:31:09Z

Hi @mattzcarey ! The vendor idea comes from openai's openai-node package. They have the same bottleneck as us which is that zod-to-json-schema's maintainers have disappeared and we are all stuck without a good option to get onto zod 3.25+.

I will get this PR cleaned up today, bother the zod-to-json-schema folks one more time, and ping you when it's ready to be merged. Thanks!

pkg-pr-new · 2025-11-17T23:10:28Z

Open in StackBlitz

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

commit: 86b51fd

pkg-pr-new · 2025-11-17T23:10:29Z

Open in StackBlitz

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

commit: 205d379

dclark27 · 2025-11-17T23:45:42Z

@mattzcarey good to review again

Give it a rip npm install @socotra/modelcontextprotocol-sdk@next

dclark27 · 2025-11-18T18:21:37Z

@mattzcarey StefanTerdell/zod-to-json-schema#180 has been merged and the _vendor folder has been removed. New changes have been brought in and merge conflicts resolved. cc @colinhacks

colinhacks · 2025-11-18T19:24:25Z

A new version of zod-to-json-schema that supports Zod 3.25+ has been released. Theoretically you could now avoid vendoring that package (but it would still require bumping the min Zod version to 3.25): https://github.com/StefanTerdell/zod-to-json-schema

dclark27 · 2025-11-18T20:45:34Z

A new version of zod-to-json-schema that supports Zod 3.25+ has been released. Theoretically you could now avoid vendoring that package (but it would still require bumping the min Zod version to 3.25): https://github.com/StefanTerdell/zod-to-json-schema

Yep! I removed it ~an hour after the PR landed.

mattzcarey · 2025-11-19T12:26:28Z

Reviewing this today. Thanks for all your work :)

mattzcarey

This looks good to me. Waiting other maintainers to have a look.

mattzcarey · 2025-11-19T16:52:35Z

Hey @dclark27 could you give maintainers permissions to fix the rebase or would you be happy to do it :)

dclark27 · 2025-11-19T16:58:23Z

@mattzcarey
Looks like my org restricts that option, can you let me know what you'd like for the rebase and I'd be happy to do it! Otherwise I can recreate this changeset under my personal github account, not ideal for PR history though

mattzcarey · 2025-11-19T17:00:15Z

Ahh dont worry about it @dclark27 it might be github freaking out but i see this.

dclark27 · 2025-11-19T17:00:33Z

@mattzcarey working on it now!

edit: good to go

felixweinberger

Huge thanks @dclark27 @colinhacks @trojanowski @mattzcarey for your patience and tenacity in making this backwards compatible and unblocking a merge! Really appreciate how much effort has gone into this.

Couple of things we want to follow-up on, but not blocking this PR. We'll take on these follow-ups on within the team before the release so we can avoid a back-and-forth.

README updates to call out dual support + make clear that it's a peerDependency and users should / can "bring their own"
Remove the pnpm-lock.yaml file as we're standardizing on npm atm
@KKonstantinov proposed adding a "stress test" for a large/complex schema to ensure it remains compatible.
There's probably ways to dedupe the tests so we don't have v3 separately.

felixweinberger · 2025-11-19T19:57:06Z

package.json

    "peerDependencies": {
-        "@cfworker/json-schema": "^4.1.1"
+        "@cfworker/json-schema": "^4.1.1",
+        "zod": "^3.25 || ^4.0"


Thanks for the additional explanation here - very helpful context to have these numbers.

I believe npm install would warn folks if they have an outdated peer dependency pinned, so it would at least not be a silent failure, so that's an additional mitigating factor. I'll also call this out in the release notes for this one.

felixweinberger · 2025-11-19T20:00:00Z

pnpm-lock.yaml

I don't think we want to officially support pnpm as we're standardizing on npm atm, but can be removed in a follow-up before we release.

felixweinberger · 2025-11-19T20:02:53Z

README.md

 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import express from 'express';
-import { z } from 'zod';


We should call out the peerDependency status on the README somewhere and that v3 and v4 are both supported. We can do that in a follow-up though.

ryoppippi · 2025-11-19T20:51:03Z

Thank you so much!!

dclark27 requested review from a team as code owners October 23, 2025 20:03

dclark27 mentioned this pull request Oct 23, 2025

feat: zod v4 #869

Closed

9 tasks

chentsulin mentioned this pull request Oct 29, 2025

Experiment for v6-beta: remove commonJS and zod 3 vercel/ai#9387

Open

felixweinberger mentioned this pull request Oct 30, 2025

Implement SEP-1613: JSON Schema 2020-12 as Default Dialect #1057

Closed

colinhacks reviewed Nov 6, 2025

View reviewed changes

trojanowski reviewed Nov 6, 2025

View reviewed changes

burkedavison mentioned this pull request Nov 7, 2025

fix(deps): update dependency zod to v4 googleapis/gcloud-mcp#272

Open

1 task

valebearzotti mentioned this pull request Nov 12, 2025

[Feature]: upgrade to zod v4 basementstudio/xmcp#259

Open

dclark27 force-pushed the feature/zod-v3-compat branch 2 times, most recently from 733dce2 to 2fce53c Compare November 17, 2025 21:54

dclark27 closed this Nov 17, 2025

dclark27 force-pushed the feature/zod-v3-compat branch from 2fce53c to df56e35 Compare November 17, 2025 23:09

chore: fix merge conflicts with latest

205d379

dclark27 reopened this Nov 17, 2025

dclark27 added 4 commits November 17, 2025 15:29

chore: use zod v4 methods for types and auth

6669217

chore: use RemovePassthrough on remaining spec params

b89200a

chore: resolve remaining as any casts

1e0b11e

chore: attempt to address node 18 test failure

3f69eae

chore: remove plans

4e79d6f

dclark27 added 6 commits November 17, 2025 15:48

chore: consolidate multiple ZodV4Internal and ZodV3Internal defs

dcfcca8

chore: formatting

e3b7027

chore: remove _vendor zod-to-json-schema

6e4cfa2

Merge branch 'main' into feature/zod-v3-compat

7cfa855

chore: remove cast

2e02c25

chore: bring in new tests from recent merge

2cef25b

chore: clean up extra function and types in compat layer

ac7d541

mattzcarey approved these changes Nov 19, 2025

View reviewed changes

dclark27 added 2 commits November 19, 2025 09:04

Merge remote-tracking branch 'upstream' into feature/zod-v3-compat

76725b6

chore: run prettier

86b51fd

KKonstantinov mentioned this pull request Nov 19, 2025

Passthrough removal part 2: Achieve 0 passthrough types. #1125

Draft

9 tasks

felixweinberger approved these changes Nov 19, 2025

View reviewed changes

KKonstantinov approved these changes Nov 19, 2025

View reviewed changes

felixweinberger merged commit 418b7f9 into modelcontextprotocol:main Nov 19, 2025
6 checks passed

mattzcarey mentioned this pull request Nov 19, 2025

fix: remove pnpm lock and regenerate package-lock #1138

Merged

9 tasks

KKonstantinov mentioned this pull request Nov 19, 2025

Follow up: unify v3 and v4 zod types via describe matrix and a test helper #1141

Merged

9 tasks

vinayak-mehta mentioned this pull request Nov 19, 2025

Support for Zod 4 rekog-labs/MCP-Nest#123

Open

This was referenced Nov 20, 2025

fix: ensure zod v3 is used to avoid issues during parameterized tool calls dynatrace-oss/dynatrace-mcp#248

Merged

Use latest MCP sdk to fix zod-to-json-schema workaround dynatrace-oss/dynatrace-mcp#251

Open

kvz mentioned this pull request Nov 21, 2025

Upgrade to Zod 4 transloadit/node-sdk#263

Open

feat: zod v4 with backwards compatibility for v3.25+ #1040

feat: zod v4 with backwards compatibility for v3.25+ #1040

Conversation

dclark27 commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How Has This Been Tested?

Comprehensive Test Coverage

Test Files Created

Breaking Changes

Types of changes

Checklist

Migration Path

Uh oh!

dclark27 commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wladyslawczyzewski commented Oct 31, 2025

Uh oh!

punkpeye commented Nov 2, 2025

Uh oh!

colinhacks commented Nov 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dclark27 Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dclark27 commented Nov 11, 2025

Uh oh!

mattzcarey commented Nov 17, 2025

Uh oh!

dclark27 commented Nov 17, 2025

Uh oh!

pkg-pr-new bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Nov 17, 2025

Uh oh!

dclark27 commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dclark27 commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colinhacks commented Nov 18, 2025

Uh oh!

dclark27 commented Nov 18, 2025

Uh oh!

mattzcarey commented Nov 19, 2025

Uh oh!

mattzcarey left a comment

Choose a reason for hiding this comment

Uh oh!

mattzcarey commented Nov 19, 2025

Uh oh!

dclark27 commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mattzcarey commented Nov 19, 2025

Uh oh!

dclark27 commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dclark27 commented Oct 23, 2025 •

edited

Loading

dclark27 commented Oct 30, 2025 •

edited

Loading

dclark27 Nov 6, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 17, 2025 •

edited

Loading

dclark27 commented Nov 17, 2025 •

edited

Loading

dclark27 commented Nov 18, 2025 •

edited

Loading

dclark27 commented Nov 19, 2025 •

edited

Loading

dclark27 commented Nov 19, 2025 •

edited

Loading

felixweinberger left a comment •

edited

Loading