Fix MCP SDK Zod v4 Incompatibility: "_parse is not a function" and "_def" Errors (-32603) in Claude Desktop, Cursor, VS Code, and Cline

Symptoms

• JSON-RPC error -32603: "w._parse is not a function. (In 'w._parse(new y6(W,F,W.path,U))', 'w._parse' is undefined)"
• JSON-RPC error -32603: "null is not an object (evaluating 'F._def')"
• MCP server tools fail to execute or list when Zod v4 is installed as a project dependency
• keyValidator._parse is not a function when calling MCP tools
• MCP server starts but tool calls return internal error -32603
• Error only occurs when Zod v4.x is installed; Zod v3.x works correctly

Error signatures

w._parse is not a function

_parse is not a function

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

keyValidator._parse is not a function

keyValidator.parse is not a function

-32603

Possible causes

• The MCP TypeScript SDK v1.17.5 has a hard dependency on Zod ^3.23.8 in its package.json and directly calls internal Zod methods (_parse, _def, _zod) that are NOT part of Zod's public API. Zod v4 removed or restructured these internal methods per the Zod v4 Library Authors Guide (https://zod.dev/library-authors).
• Package manager hoisting causes silent version mismatches: npm, yarn, pnpm, and bun may hoist a root-level Zod v4 above the MCP SDK's Zod v3. Even when `npm list zod` shows v3, the runtime may load the hoisted v4. This is common in monorepos where another package depends on Zod v4 and the package manager deduplicates to v4 at the root, overriding the MCP SDK's v3 constraint.
• The npm caret range `^3.23.8` explicitly excludes Zod v4.x (semver major version change). However, `npm install zod@4` followed by `npm install @modelcontextprotocol/sdk` may leave Zod v4 in node_modules if the package manager doesn't force-deduplicate to v3.
• The error `w._parse is not a function` comes from the minified SDK bundle where the Zod schema's internal `_parse` method is called during tool input validation. In Zod v4, this method no longer exists on schema objects — validation must use the top-level `parse()` or `safeParse()` functions.
• The MCP SDK uses `_def` (Zod's internal schema definition property) for schema introspection. In Zod v4, the `_def` structure changed significantly, causing the `null is not an object (evaluating 'F._def')` error.

Solutions

npm install zod@^4.0.0

node -e "const {z} = require('zod/v3'); console.log('zod/v3 loaded:', typeof z.string)"

// Replace:
import { z } from 'zod';

// With:
import { z } from 'zod/v3';

npm install zod@^3.23.8

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

npm ls zod

node -e "const z = require('zod'); console.log('Zod version:', z.version || 'v3.x')"

{
  "name": "my-mcp-server",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.17.5",
    "zod": "^4.1.5"
  },
  "overrides": {
    "zod": "^3.23.8"
  }
}

npm install @modelcontextprotocol/sdk@latest

npm view @modelcontextprotocol/sdk@1.17.5 dependencies.zod

npm view @modelcontextprotocol/sdk@1.23.1 dependencies.zod

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

npm ls zod

Agent JSON

Canonical machine-readable representation of this issue:

{
  "issue_id": "001da997-496c-4ea8-87a5-bc1ab9ce9641",
  "slug": "fix-mcp-sdk-zod-v4-incompatibility-parse-is-not-a-function-and-def-errors-32603-in-claude-desktop-cursor-vs-code-and-cli-yvhwvp",
  "verification_status": "unverified",
  "canonical_json": "https://codekb.dev/v1/issues/fix-mcp-sdk-zod-v4-incompatibility-parse-is-not-a-function-and-def-errors-32603-in-claude-desktop-cursor-vs-code-and-cli-yvhwvp"
}