Why MCP Tools Use Zod v3

Problem

FastMCP uses xsschema to convert schemas → outputs JSON Schema Draft 2020-12
MCP clients (Augment IDE, gemini-cli, etc.) only support Draft-07
Using Zod v4 in tools causes "vendor undefined" errors and tool discovery failures

Temporary Solution

All MCP tool files import from zod/v3 instead of zod:

import { z } from 'zod/v3';  // ✅ Draft-07 compatible
// NOT: import { z } from 'zod';  // ❌ Would use Draft 2020-12

Why This Works

Zod v4 ships with v3 compatibility at zod/v3
FastMCP + zod-to-json-schema converts Zod v3 schemas → Draft-07
This ensures MCP clients can discover and use our tools

What This Means

✅ MCP tools → use zod/v3 (this directory)
✅ Rest of codebase → uses zod (Zod v4)
✅ No conflicts → they're from the same package, just different versions

When Can We Remove This?

This workaround can be removed when either:

FastMCP adds JSON Schema version configuration
- e.g., new FastMCP({ jsonSchema: { target: 'draft-07' } })
- Tracking: https://github.com/punkpeye/fastmcp/issues/189
MCP spec adds Draft 2020-12 support
- Unlikely in the short term
xsschema adds version targeting
- Would allow FastMCP to use Draft-07

How to Maintain

When adding new MCP tools:

// ✅ CORRECT
import { z } from 'zod/v3';

server.addTool({
  name: 'my_tool',
  parameters: z.object({ ... }),  // Will use Draft-07
  execute: async (args) => { ... }
});

// ❌ WRONG - Will break MCP client compatibility
import { z } from 'zod';  // Don't do this in mcp-server/src/tools/

Last Updated: 2025-10-18 Affects: All files in mcp-server/src/tools/

1.8 KiB Raw Blame History