Pin one zod copy that matches your MCP SDK to avoid type errors
You will align your project so only one zod copy is installed and it matches the version the MCP TypeScript SDK uses. This reduces the risk of registerTool schema type errors caused by duplicate zod installs.
- Find zod copiesList zod versions to spot duplicates.
- Match SDK zodUse the version the SDK bundles.
- Pin and overrideForce one copy in your config.
- Clean reinstallRemove node_modules and lockfile.
- Compile checkConfirm registerTool schemas compile.
Why it matters
A developer building tools with the MCP TypeScript SDK hit a compile error when passing a z.string() input schema to server.registerTool. Their own zod (3.23.8) differed from the zod the SDK bundles (3.25.76), so TypeScript saw two incompatible ZodString types and reported missing ~standard and ~validate properties. The thread is issue #802 (opens external site). It is closed as completed, but the thread does not confirm that the fix removes this exact v3 error, so verify it in your own project.
Steps
- List every zod copy in your dependency tree with your package manager, for example
npm ls zod. Look for more than one version. - Identify the zod version the SDK bundles in your setup. The reporter in issue #802 saw 3.25.76, but check your own installed SDK version rather than assuming that number.
- Pin your direct zod dependency to that same exact version in your
package.json, so a range cannot resolve to a different copy. - Force a single copy using your package manager's override feature, such as an overrides setting in npm or a resolutions setting in yarn. This is general package-manager practice, not syntax shown in the thread, so follow your package manager's own documentation for the exact format.
- Delete
node_modulesand the lockfile, reinstall, and run your list command again to confirm one zod version appears. - Run the TypeScript compiler on the file that calls
registerTooland confirm the input schema compiles without the~standarderror. - If you want the newer line, maintainers released beta
1.23.0-beta.0on 2025-11-21 with backwards compatible zod v4 support. The thread does not confirm it removes this exact v3 error, so test it on a branch and recheck your schemas before upgrading.
Common mistakes
- Adding zod with a caret range and assuming the SDK will use your copy. If the SDK brings its own zod, you can end up with two types.
- Moving to zod v4 on the stable SDK line before checking compatibility. One user in the thread reported incompatibility before the beta.
- Hiding the error with a type cast. That leaves the duplicate installs in place.
- Pinning once and forgetting. Recheck your zod list after each SDK upgrade, since the bundled version can change.
Background on related setup
If you also use a CommonJS client, issue #203 (opens external site) reports an ERR_REQUIRE_ESM error on the SSE client path. One user said upgrading to v1.9.0 made the problem go away. No maintainer confirmed that in the thread, so treat it as a single user report. Record your SDK version in your lockfile so these changes are easy to trace.
Checklist
0 of 8 done