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:

1. FastMCP adds JSON Schema version configuration

   • e.g., new FastMCP({ jsonSchema: { target: 'draft-07' } })
   • Tracking: https://github.com/punkpeye/fastmcp/issues/189

2. MCP spec adds Draft 2020-12 support

   • Unlikely in the short term

3. 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/