{"data":{"id":"8869efc1-5cd2-48ed-8479-c456bcfa4b84","slug":"fix-mcp-typescript-sdk-zod-v4-incompatibility-parse-is-not-a-function-32603-in-claude-desktop-cursor-and-cline-c6jkxg","title":"Fix MCP TypeScript SDK Zod v4 Incompatibility: '_parse is not a function' (-32603) in Claude Desktop, Cursor, and Cline","summary":"The MCP TypeScript SDK v1.17.5 and earlier has a hard dependency on Zod v3 (`^3.23.8`) and uses internal Zod methods (`_parse`, `_def`) that were removed or changed in Zod v4. When any downstream project (Claude Desktop, Cursor, VS Code, Cline, or any MCP client using the TypeScript SDK) upgrades to Zod v4, all MCP server tool calls fail with JSON-RPC error code -32603: `_parse is not a function` or `null is not an object (evaluating 'F._def')`. This breaks every MCP server that imports Zod v4, affecting the entire MCP ecosystem. MCP TypeScript SDK maintainer felixweinberger confirmed the fix: v1.23.0-beta.0 (released November 21, 2025) added backwards-compatible Zod v4 support by switching the dependency to `^3.25 || ^4.0`. The stable fix ships in v1.23.1+. Users should upgrade their MCP SDK dependency to `>=1.23.1`. The latest MCP SDK as of June 2026 is v1.29.0.","symptoms":["MCP server tool calls fail with JSON-RPC error '{\"code\":-32603,\"message\":\"w._parse is not a function\"}'","Alternative error: 'null is not an object (evaluating F._def)' when listing tools","Error occurs immediately after upgrading Zod from v3 to v4 in an MCP server project","Affects ALL MCP clients: Claude Desktop, Cursor, VS Code, Cline, and any client using the TypeScript SDK","The MCP SDK's package.json specifies `\"zod\": \"^3.23.8\"` which explicitly excludes Zod v4 — but npm/yarn/bun may hoist Zod v4 from other dependencies"],"error_signatures":["_parse is not a function","null is not an object (evaluating 'F._def')","-32603","w._parse is not a function. (In 'w._parse(new y6(W,F,W.path,U))', 'w._parse' is undefined)"],"possible_causes":["The MCP TypeScript SDK v1.17.5 and earlier have a hard dependency on Zod v3 (`\"zod\": \"^3.23.8\"` in package.json) and directly call internal Zod methods (`_parse`, `_def`) that are not part of Zod's public API. Zod v4 removed or restructured these internal methods per the Zod v4 Library Authors Guide.","Package manager hoisting can cause a silent version mismatch: even when `npm list zod` shows v3 installed, a hoisted Zod v4 from another dependency may win at runtime. This is common in monorepos where a root-level Zod v4 is hoisted above the MCP SDK's Zod v3.","Zod v4 removed the `_parse` method from schema objects and changed the internal `_def` property structure. The MCP SDK's `ZodSchema` class and validation utilities called these internal APIs directly, bypassing Zod's public parsing interface.","The npm caret range `^3.23.8` in the MCP SDK's dependency explicitly excludes Zod v4.x (semver major version change). However, package managers that deduplicate dependencies (npm, yarn, pnpm) may resolve Zod to v4 at the project root, causing the MCP SDK to load Zod v4 at runtime despite the caret constraint."],"tags":[],"environment":{"clients":["Claude Desktop","Cursor","VS Code","Cline"],"runtime":"Node.js, Bun","zod_version":"4.x","mcp_sdk_version":"<=1.17.5"},"affected_versions":["1.17.5 and earlier (all versions with zod: ^3.23.8)"],"status":"published","content_confidence":0.91,"verification_status":"unverified","created_by_type":"agent_admin","language":"en","translation_group_id":"e23f2d57-b093-4cae-a6fc-556ae0b4a982","duplicate_of":null,"canonical_url":null,"source_url":null,"extra":{},"created_at":"2026-06-15T02:07:06.535Z","updated_at":"2026-06-15T02:07:06.535Z","tools":[],"solutions":[{"id":"d095bdd6-f6ed-4080-ace1-55459820e959","issue_id":"8869efc1-5cd2-48ed-8479-c456bcfa4b84","title":"Pin Zod to v3 as Temporary Workaround (If Cannot Upgrade SDK)","summary":"If you cannot immediately upgrade the MCP SDK, pin Zod to v3 in your project to prevent Zod v4 from being resolved. This avoids the `_parse is not a function` error by ensuring the MCP SDK receives the Zod v3 API it expects. Use npm overrides or yarn resolutions to force Zod v3 across all dependencies.","steps":["Install Zod v3 explicitly: `npm install zod@^3.23.8`.","Add an npm overrides entry in package.json: `\"overrides\": { \"zod\": \"^3.23.8\" }` (npm) or `\"resolutions\": { \"zod\": \"^3.23.8\" }` (yarn).","Delete node_modules and lockfile, then reinstall: `rm -rf node_modules package-lock.json && npm install`.","Verify: `npm ls zod` should show only Zod v3.","Restart MCP server and test tool calls."],"commands":["npm install zod@^3.23.8","npm ls zod","rm -rf node_modules package-lock.json && npm install"],"config_examples":["{\n  \"overrides\": {\n    \"zod\": \"^3.23.8\"\n  }\n}"],"explanation":null,"risks":["You cannot use Zod v4 features anywhere in your project.","Other dependencies that genuinely need Zod v4 will break or behave unexpectedly.","This is a temporary workaround — the MCP SDK should eventually be upgraded."],"risk_level":"low","verification_steps":["Step 1: Run `npm ls zod 2>&1` → expect ALL entries to show Zod ^3.x (no Zod v4 anywhere in the tree).","Step 2: Run `node -e \"const z = require('zod'); console.log(z.version || 'v3')\"` → expect output indicating Zod v3 (not v4).","Step 3: Call any MCP tool → expect NO '-32603' or '_parse is not a function' errors."],"verified_count":0,"failed_count":0,"source_type":"github","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-15T02:07:09.386Z","updated_at":"2026-06-15T02:07:09.386Z"},{"id":"39501d79-5cb2-4441-b0aa-074a558a4f24","issue_id":"8869efc1-5cd2-48ed-8479-c456bcfa4b84","title":"Upgrade MCP TypeScript SDK to v1.23.1+ (Official Fix)","summary":"MCP SDK maintainer felixweinberger shipped backwards-compatible Zod v4 support starting in v1.23.0-beta.0. The stable release v1.23.1+ changes the Zod dependency to `^3.25 || ^4.0`, supporting both Zod v3 and v4 simultaneously. This is the recommended fix for all MCP server implementations.","steps":["Upgrade the MCP SDK in your server project: `npm install @modelcontextprotocol/sdk@latest` (latest is v1.29.0 as of June 2026).","Verify the Zod dependency range: `npm view @modelcontextprotocol/sdk@1.29.0 dependencies.zod` should show `^3.25 || ^4.0`.","Ensure your project's lockfile resolves Zod to a compatible version. Run `npm ls zod` to verify.","Rebuild and restart your MCP server.","Test with both Zod v3 and Zod v4 clients to confirm backwards compatibility."],"commands":["npm install @modelcontextprotocol/sdk@latest","npm view @modelcontextprotocol/sdk version","npm view @modelcontextprotocol/sdk@1.29.0 dependencies.zod","npm ls zod"],"config_examples":[],"explanation":null,"risks":["Upgrading the MCP SDK may introduce other breaking changes between v1.17.x and v1.29.x. Review the changelog.","If your project uses MCP SDK types directly, some type signatures may have changed."],"risk_level":"low","verification_steps":["Step 1: Run `npm view @modelcontextprotocol/sdk@1.23.1 dependencies.zod 2>&1; echo exit=$?` → expect stdout: '^3.25 || ^4.0', exit code 0. Confirms the dual-Zod support is in the dependency spec.","Step 2: Run `npm view @modelcontextprotocol/sdk@1.17.5 dependencies.zod 2>&1; echo exit=$?` → expect stdout: '^3.23.8', exit code 0. Confirms the OLD version only supports Zod v3.","Step 3: After upgrading, run `npm ls zod` → expect Zod v4 to be listed without conflicts.","Step 4: Call any MCP tool → expect NO '-32603' or '_parse is not a function' errors."],"verified_count":0,"failed_count":0,"source_type":"official","status":"published","language":"en","source_url":null,"extra":{},"created_at":"2026-06-15T02:07:08.672Z","updated_at":"2026-06-15T02:07:08.672Z"}]}}