feat: zod v4

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040

[dclark27]

Summary

• Upgrade to zod v4
• Replaces zod-to-json-schema with zod v4 toJsonSchema
• Adjust usage to be in best practice with zod v4 migration guide
• Adjust imports to use import * as z from 'zod' instead of import { z } from 'zod' to prevent memory leaks

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

• npm test → 37 suites / 755 tests / 0 failures (macOS, Node ≥18)
• Published and running on Socotra's MCP server which hosts dozens of tools and completions

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4+

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• 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
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

[ihrpr]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

[dclark27]

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

[dclark27]

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

[ochafik]

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

[dvanmali]

Another temporary fix (beyond previously mentioned "overrides" method), useful if your package wishes to use v4.

{
"resolution": {
"@modelcontextprotocol/sdk>zod": "^3.23.8",
}
}

[dclark27]

Thanks for everyone's patience. This PR has been updated to:

• Implement feedback from comments on this PR (thank you!)
• Resolved merge conflicts
• Fix formatting
• Changed how we import from zod to use the import * as z from 'zod'

Testing this in our own MCP server I am not seeing any memory leaks (as I was when importing from import { z } from 'zod') and it matches the guidance from Zod's migration guide.

I think the deciding factor here is around the z.toJsonSchema. Because zod-to-json-schema is no longer maintained, we need to either write our own version of it, use an aliased package that other people have forked and published, or save this PR for a v2 when we are ok with breaking changes.

In the meantime, feel free and test using npm i @socotra/modelcontextprotocol-sdk

@felixweinberger I saw your PR from 5 days ago. Feel free and take the lead on this if you'd like to implement separately.

[dclark27]

Just put up a new PR with backwards compatibility after a discussion with Colin Hacks on X.

#1040

[JFrogKevinz]

Do you have ETA for release of this feature ?

[dclark27]

Closing in favor of #1040