MCP TypeScript SDK generates JSON Schema draft-07, breaking compatibility with modern MCP clients requiring draft-2020-12

[Sunsvea]

Describe the bug
The MCP TypeScript SDK generates JSON Schema draft-07 via zod-to-json-schema@3.24.5, causing 400 errors when MCP servers are used with modern MCP clients (e.g. Claude Code in this report), which requires strict compliance with JSON Schema draft-2020-12. This breaks compatibility between the MCP ecosystem & Claude Code.

To Reproduce (Claude Code)

1. Create an MCP server using the TypeScript SDK with any Zod schema (e.g., Mapbox MCP Server)
2. Build and run the MCP server
3. Configure Claude Code to use the MCP server
4. Attempt to use any tool from the MCP server in Claude Code
5. Observe 400 error: "JSON schema is invalid. It must match JSON Schema draft 2020-12"

Expected behavior
MCP servers built with the TypeScript SDK should generate JSON Schema draft-2020-12 compatible schemas that work seamlessly with Claude Code (and other popular MCP clients) and other modern JSON Schema validators.

Logs
Error from Claude Code:

> Hi there!
  ⎿ API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.74.custom.input_schema: JSON schema is invalid. It must
     match JSON Schema draft 2020-12 (https://json-schema.org/draft/2020-12). Learn more about tool use at
    https://docs.anthropic.com/en/docs/tool-use."}}

> What the!!
  ⎿ API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"tools.54.custom.input_schema: JSON schema is invalid. It must
     match JSON Schema draft 2020-12 (https://json-schema.org/draft/2020-12). Learn more about tool use at
    https://docs.anthropic.com/en/docs/tool-use."}}

Root cause in https://github.com/modelcontextprotocol/typescript-sdk/blob/main/src/server/mcp.ts:

  zodToJsonSchema(tool.inputSchema, {
      strictUnions: true,
  })

Additional context

• Root cause: SDK uses zod-to-json-schema@3.24.5 which defaults to draft-07
• Impact: Affects all MCP servers using TypeScript SDK (Mapbox, database connectors, etc.)
• Related issues:
  • [BUG] JSON schema is invalid. It must match JSON Schema draft 2020-12 anthropics/claude-code#586 - Claude Code compatibility issue
  • Discussion: Schema's problem rust-sdk#182 - Similar issue in Rust SDK
  • Discussion Update README.md to use correct location of InMemoryEventStore #366 - Schema draft standards discussion
• Solution: Upgrade to Zod v4's native toJSONSchema({ target: "draft-2020-12" }) or configure zod-to-json-schema for draft-2020-12 output
• Environment: @modelcontextprotocol/sdk@1.12.1, zod-to-json-schema@3.24.5

[Sunsvea]

I generated some schema diffs for context:

Current MCP SDK Output (Draft-07):

  {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "proximity": {
        "type": "array",
        "minItems": 2,
        "maxItems": 2,
        "items": [
          { "type": "number" },
          { "type": "number" }
        ]
      }
    }
  }

Required for Claude Code (Draft-2020-12):

  {
    "$schema": "https://json-schema.org/draft/2020-12/schema#",
    "type": "object",
    "properties": {
      "proximity": {
        "type": "array",
        "prefixItems": [
          { "type": "number" },
          { "type": "number" }
        ],
        "items": false,
        "minItems": 2,
        "maxItems": 2
      }
    }
  }

Critical Differences between the schema versions:

1. $schema URL:
   - Draft-07: http://json-schema.org/draft-07/schema#
   - Draft-2020-12: https://json-schema.org/draft/2020-12/schema#
2. Tuple validation syntax:
   - Draft-07: "items": [...] (array of schemas)
   - Draft-2020-12: "prefixItems": [...], "items": false
3. Schema validation strictness:
   - Claude Code validates the $schema declaration and rejects draft-07
   - New tuple syntax is incompatible between versions

[Mihailoff]

SDK should upgrade to Zod v4.

z.toJSONSchema(schema, { target: "draft-7" });
z.toJSONSchema(schema, { target: "draft-2020-12" });

https://zod.dev/json-schema#target

---

There are complications though. For example, zod-to-json-schema handles zod dates nicely -- { type: 'string', format: 'date-time' }, whereas z.toJSONSchema have it as https://zod.dev/json-schema#unrepresentable and either will throw an error or omit it as {}.

Ideally, zod v4 + zod-to-json-schema that supports it. Or colinhacks/zod#4995