Cursor Model Context ProtocolUnverified

Fix MCP TypeScript SDK Zod v4 Incompatibility: '_parse is not a function' (-32603) in Claude Desktop, Cursor, VS Code, and Custom MCP Servers

MCP TypeScript SDK v1.17.0 through v1.17.5 is incompatible with Zod v4.x due to breaking changes in Zod's internal API. When projects use Zod v4 alongside the MCP SDK, tools fail with JSON-RPC error -32603: 'w._parse is not a function' and 'null is not an object (evaluating F._def)'. Root cause: the MCP SDK directly calls internal Zod methods (_parse, _def) that were removed or changed in Zod v4. The fix was shipped in MCP SDK v1.23.0-beta.0 and stable v1.23.0+ by maintainer felixweinberger, who added backward-compatible Zod v4 support via PR #869. This affects all MCP server implementations using the TypeScript SDK, including Claude Desktop, Cursor, VS Code, Cline, and any custom MCP server built with @modelcontextprotocol/sdk. NPM/Bun dependency resolution can silently hoist Zod v4 even when the SDK specifies zod@^3, causing the error to appear without explicit Zod v4 installation. Workarounds include upgrading the SDK to v1.23.0+, pinning Zod to v3.x in package.json overrides, or using the v1.23.0-beta.0 release for early adoption.

Symptoms

MCP tools fail to execute with error: 'w._parse is not a function. (In w._parse(new y6(W,F,W.path,U)), w._parse is undefined)'
MCP tools list returns error: 'null is not an object (evaluating F._def)'
MCP server tools appear to register but fail when invoked
Error occurs specifically when Zod v4.x is installed alongside MCP SDK v1.17.5 or earlier
JSON-RPC error response with code -32603 (internal error)

Error signatures

w._parse is not a function

null is not an object (evaluating 'F._def')

{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"w._parse is not a function..."}}

{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"null is not an object (evaluating 'F._def')"}}

Possible causes

Zod v4 introduced breaking changes to internal API — the _parse and _def methods that MCP SDK calls directly were removed or changed signature in Zod v4 (per Zod v4 Library Authors Guide at zod.dev/library-authors)
MCP SDK v1.17.5 has a hard dependency on zod@^3.23.8 in its package.json, but npm/yarn/bun's dependency resolution can hoist zod@4 if another dependency or the project root requires it — the caret range ^3.23.8 allows npm to install zod@3.x but does NOT prevent a hoisted zod@4 from being used at runtime
This is a silent failure mode: npm list zod may show zod@3 in the SDK's node_modules, but require('zod') resolves to the hoisted zod@4 from the project root, causing the SDK to use the wrong Zod version
The MCP SDK uses internal Zod methods (_parse, _def) rather than the public API, making it fragile to major version changes — Zod v4 specifically requires library authors to use compatibility patterns (e.g., _zod property checks, top-level parsing functions instead of schema methods per the Library Authors Guide)
Bun's module resolution is particularly aggressive with hoisting, so Bun users may hit this error even when npm users on the same project do not

Solutions

Use MCP SDK v1.23.0-beta.0 for Early Zod v4 Adoption

risk: lowofficialpublished

Install the specific beta release that first introduced Zod v4 backward compatibility. The maintainer (felixweinberger) explicitly requested feedback on this beta. Use this if you need Zod v4 features immediately and are willing to test beta software.

Install the exact beta version: npm install @modelcontextprotocol/sdk@1.23.0-beta.0
Ensure Zod v4 is explicitly installed: npm install zod@4.1.5
Rebuild and restart your MCP server
Test all tools, especially those using Zod v4 schemas with z.toJSONSchema() or complex refinements
Report any issues to https://github.com/modelcontextprotocol/typescript-sdk/issues

Commands

npm install @modelcontextprotocol/sdk@1.23.0-beta.0 zod@4.1.5

npm list @modelcontextprotocol/sdk zod

Risks

Beta releases may contain bugs or incomplete features — not recommended for production use
API surface may differ slightly from the final 1.23.0 stable release
The maintainer specifically requested feedback on this beta — be prepared to report issues

Verification

Step 1: Run npm list @modelcontextprotocol/sdk → expect: '1.23.0-beta.0'
Step 2: Run npm list zod → expect: zod@4.1.5 listed without peer dependency warnings
Step 3: Invoke a tool using Zod v4's z.toJSONSchema() → expect: tool returns valid JSON-RPC result, no error field

✓ 0 verified✕ 0 failed

Pin Zod to v3.x with npm Overrides (Temporary Workaround)

risk: lowgithubpublished

If you cannot immediately upgrade the MCP SDK, pin Zod to version 3.x using npm overrides (or yarn resolutions / bun overrides) to prevent the incompatible v4.x from being hoisted. This forces all dependencies, including transitive ones, to use zod@3.23.8.

Check which Zod version is currently resolved at runtime: node -e "console.log(require('zod/package.json').version)"
Add an overrides field to package.json to force zod@3.23.8 for all dependency subtrees
Delete node_modules and package-lock.json, then reinstall: rm -rf node_modules package-lock.json && npm install
Verify the runtime Zod version is now v3, not v4
Rebuild and restart your MCP server, then test tool execution

Commands

node -e "console.log(require('zod/package.json').version)"

rm -rf node_modules package-lock.json && npm install

npm list zod --depth=10 | grep zod@

Config examples

{
  "overrides": {
    "zod": "3.23.8"
  }
}

Risks

Pinning Zod to v3 means you cannot use Zod v4 features (z.toJSONSchema(), improved type inference, smaller bundle size)
Other dependencies that genuinely require Zod v4 may break if their v4-specific APIs are used
This is a temporary workaround — upgrading the MCP SDK to v1.23.0+ is the proper long-term fix
For Yarn users, use 'resolutions' instead of 'overrides'; for Bun users, use bunfig.toml [install.overrides]

Verification

Step 1: Run node -e "console.log(require('zod/package.json').version)" → expect: '3.23.8' (NOT '4.x.x')
Step 2: Run npm ls zod → expect: no zod@4 entries anywhere in the dependency tree
Step 3: Restart MCP server and invoke a tool with Zod schema → expect: JSON-RPC response with result field, no error.code -32603

✓ 0 verified✕ 0 failed

Upgrade MCP TypeScript SDK to v1.23.0+ (Recommended — Official Fix)

risk: lowofficialpublished

Upgrade @modelcontextprotocol/sdk to v1.23.0 or later, which includes backward-compatible Zod v4 support. This is the official fix, validated by MCP SDK maintainer felixweinberger and shipped in the 1.23.x stable release line. The latest version as of June 2026 is v1.29.0.

Check your current MCP SDK version and dependency tree: npm list @modelcontextprotocol/sdk zod
Upgrade to the latest version: npm install @modelcontextprotocol/sdk@latest
Verify the upgrade resolved the Zod compatibility: check that the SDK's source no longer calls raw _parse/_def on Zod v4 objects
Rebuild your MCP server and restart all connected clients (Claude Desktop, Cursor, VS Code, Cline)
Test tool execution with both Zod v3 and Zod v4 schemas to confirm backward compatibility

Commands

npm list @modelcontextprotocol/sdk zod --depth=0

npm install @modelcontextprotocol/sdk@latest

npm list @modelcontextprotocol/sdk

Risks

Upgrading from 1.17.x to 1.29.0 may include other breaking changes in the SDK API — review the full changelog at https://github.com/modelcontextprotocol/typescript-sdk/releases
The 1.23.0-beta.0 release is a beta — prefer stable 1.23.0 or later for production use

Verification

Step 1: Run npm list @modelcontextprotocol/sdk → expect: version 1.23.0 or later (e.g., '1.23.0', '1.23.1', or '1.29.0')
Step 2: Run npm list zod → expect: zod@4.x appears in the tree without peer dependency warnings
Step 3: Restart your MCP server and invoke a tool using Zod v4's z.toJSONSchema() → expect: tool executes successfully, JSON-RPC response has no error field
Step 4: Run grep -r '_parse' node_modules/@modelcontextprotocol/sdk/dist/ → expect: no results (internal Zod methods no longer called directly)

✓ 0 verified✕ 0 failed

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "b91a4121-f0d9-4096-a0bb-7f9038975390",
  "slug": "fix-mcp-typescript-sdk-zod-v4-incompatibility-parse-is-not-a-function-32603-in-claude-desktop-cursor-vs-code-and-custom--1bedz0",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-mcp-typescript-sdk-zod-v4-incompatibility-parse-is-not-a-function-32603-in-claude-desktop-cursor-vs-code-and-custom--1bedz0"
}