Zod version compatibility issue with MCP SDK

[developermau]

While, I am builidng a custom MCP server about fetching data from Disney API. I have this error: keyValidator.parse is not a function.

Cursor found out a Zod version compatibility issue with MCP SDK:

There's a version conflict:

• Your project has Zod 4.1.4 installed
• But the MCP SDK is using Zod 3.25.76 internally
• This version mismatch is causing the keyValidator._parse is not a function error

The solution is to downgrade your Zod version to be compatible with the MCP SDK. But the latest version of Zod is 4.1.5.

Please, if it is possible, you might give support to the latest of version of Zod. Or maybe, there is a best way to solve this kind of issues.

I would appreciate your help. Have a nice day!

[orlov-vo]

Agreed! As temporary workaround you can use old version of zod in mcp declarations, just add it to package.json and install packages:

"mcp-zod": "npm:zod@3.25.76"

and use it in your declarations:

// import { z } from "zod";
import { z as mcpZod } from "mcp-zod";
const z = mcpZod as unknown as typeof import("zod").z;

mcpServer.registerTool(
  "roll_dice",
  {
    description: "Rolls an N-sided die",
    inputSchema: {
      sides: z.number().int().min(2).describe("The number of sides on the die"),
    },
  },
  async ({ sides }) => {
    const value = 1 + Math.floor(Math.random() * sides);
    return {
      content: [{ type: "text", text: `🎲 You rolled a ${value}!` }],
    };
  },
);

[Karljoy973]

Im not sure they allow the use of zod 4 as it might create some breaking changes.

[tmkn]

@developermau you can import Zod 3 via import { z } from "zod/v3"; from a Zod 4 version

[developermau]

@developermau you can import Zod 3 via import { z } from "zod/v3"; from a Zod 4 version

Thanks @tmkn ! I tried it (import { z } from "zod/v3";). However, I have another error: Type instantiation is excessively deep and possibly infinite..

"dependencies": {
    "@modelcontextprotocol/sdk": "^1.17.4",
    "zod": "^4.1.5"
  },

Part of the code:

import { z } from "zod/v3";
// More code

server.tool(
  "filter_character_by_name",
  "Filter a specific character using the character?params endpoint.",
  {
    name: z.string().describe("Character name"),
  },
  async (args) => {
    // 68 lines of code 👀
  }
);

[developermau]

Agreed! As temporary workaround you can use old version of zod in mcp declarations, just add it to package.json and install packages:

"mcp-zod": "npm:zod@3.25.76"
and use it in your declarations:

// import { z } from "zod";
import { z as mcpZod } from "mcp-zod";
const z = mcpZod as unknown as typeof import("zod").z;

mcpServer.registerTool(
"roll_dice",
{
description: "Rolls an N-sided die",
inputSchema: {
sides: z.number().int().min(2).describe("The number of sides on the die"),
},
},
async ({ sides }) => {
const value = 1 + Math.floor(Math.random() * sides);
return {
content: [{ type: "text", text: 🎲 You rolled a ${value}! }],
};
},
);

Thanks @orlov-vo ! It works!

"dependencies": {
    "mcp-zod": "npm:zod@3.25.76",
    "@modelcontextprotocol/sdk": "^1.17.4",
    "zod": "^4.1.5"
  },

Part of the code:

import { z as mcpZod } from "mcp-zod";
const z = mcpZod as unknown as typeof import("zod").z;

// More code

server.tool(
  "filter_character_by_name",
  "Filter a specific character using the character?params endpoint.",
  {
    name: z.string().describe("Character name"),
  },
  async (args) => {
    // More code
  }
);

[justin-schroeder]

I just released this to help this exact problem: https://zodown.com/

const v3schema = zodown(v4schema)