zod v4: toJSONSchema options are hardcoded — z.date() breaks tools/list; output schemas advertise required/closed shapes the raw structuredContent can't satisfy

[jtemps]

Summary

When tools use zod v4 schemas, the SDK's zod→JSON Schema conversion (server/zod-json-schema-compat.ts, toJsonSchemaCompat) calls zod's native toJSONSchema with hardcoded options and no passthrough, producing three behaviors that break real servers. All three stem from the same asymmetry: the SDK converts and validates with the tool's zod schema, but sends the tool's raw structuredContent object (validation does not replace/serialize the payload), so the advertised schema must describe the serialized form of a raw object.

Versions: @modelcontextprotocol/sdk 1.29.0, zod 4.4.3.

1. z.date() anywhere in a tool schema kills tools/list

zod v4's toJSONSchema defaults to unrepresentable: "throw", so listing tools throws:

McpError: MCP error -32603: Date cannot be represented in JSON Schema

The zod v3 path (vendored zod-to-json-schema) rendered z.date() as { "type": "string", "format": "date-time" } — which is also what JSON.stringify actually puts on the wire for a Date. Servers migrating v3→v4 with Date-valued fields (e.g. ORM entities) lose tools/list entirely. Switching schemas to z.iso.datetime() is not a workaround: server-side output validation then rejects the tools' raw Date values before serialization (isError: true, "expected string").

2. Defaulted output-schema fields are advertised as required

With io: "output" semantics, zod v4 lists .default() fields in required. But the server ships the tool's raw return value — zod never fills defaults into the response — so a tool that omits a defaulted field violates its own advertised schema, and spec-compliant validating clients reject the response. (zod-to-json-schema kept defaulted fields optional.)

3. additionalProperties: false on output objects can't be honored

Plain z.object() converts with additionalProperties: false on outputs, while zod validation tolerates and passes through unknown keys on the raw object. Any tool returning extra keys (very common when returning spread ORM/service objects) produces responses that validating clients reject. We caught four production tools failing this way once we added client-side ajv validation of serialized results.

Repro (issues 1 & 2 in one tool)

const server = new McpServer({ name: "repro", version: "1.0.0" });
server.registerTool(
  "t",
  {
    description: "repro",
    inputSchema: { when: z.date() },                       // (1) tools/list throws
    outputSchema: { counted: z.number().default(0),        // (2) advertised as required
                    name: z.string() },
  },
  async () => ({ content: [], structuredContent: { name: "x" } }) // omits `counted` → strict clients reject
);

Proposal

Either (preferred, minimal) expose conversion options on registerTool/server config — at least unrepresentable and override passthrough to toJSONSchema — or make the defaults wire-truthful:

• unrepresentable: "any" + render ZodDate as { type: "string", format: "date-time" } (matches serialization and the v3 path),
• drop defaulted fields from required in output conversion,
• drop additionalProperties: false in output conversion (or strip unknown keys during output validation so the promise is actually kept).

We currently carry exactly these three adjustments as a ~30-line pnpm patch to zod-json-schema-compat (both dists), with contract tests pinning the behaviors — happy to send a PR if maintainers agree on the direction.

[mcp-claude]

reproduces on current main (24be404, @modelcontextprotocol/server 2.0.0-beta.2, zod 4.3.6). all three symptoms in the report are present, and the same conversion path exists on v1.x (src/server/zod-json-schema-compat.ts calls z4mini.toJSONSchema with only target+io), so a fix likely needs backporting.

the SDK's own client also fails to round-trip its own server: Client.callTool re-validates structuredContent with strict json-schema (ajv), and rejects payloads whose defaulted fields are missing or that carry extras — matching the "spec-compliant validating clients reject the response" claim.

root cause is in packages/core-internal/src/util/standardSchema.ts at standardSchemaToJsonSchema: it calls std.jsonSchema[io]({ target: 'draft-2020-12' }) (and the 4.0–4.1 fallback calls z.toJSONSchema(...) similarly) with no unrepresentable, no override, and no post-processing, so the advertised schema doesn't describe what the server ships. output-side fix options: (a) rewrite ZodDate → {type:"string", format:"date-time"} and set unrepresentable:"any", (b) strip defaulted-field names from required under io:"output", (c) drop additionalProperties:false under io:"output" (or actually strip unknown keys during output validation).

repro.ts — schema-level, exercises all three symptoms

import * as z from 'zod/v4';
import {
    standardSchemaToJsonSchema,
    validateStandardSchema,
    InMemoryTransport
} from '@modelcontextprotocol/core-internal';
import { McpServer } from '@modelcontextprotocol/server';
import { Client } from '@modelcontextprotocol/client';

// (1) z.date() input
try {
    standardSchemaToJsonSchema(z.object({ when: z.date() }) as any, 'input');
} catch (e) { console.log('(1) THROWS:', (e as Error).message); }

// (2) defaulted output field
const out = z.object({ counted: z.number().default(0), name: z.string() });
const j = standardSchemaToJsonSchema(out as any, 'output');
console.log('(2) output json:', JSON.stringify(j));
console.log('(2b) SDK validate({name:"x"}):', JSON.stringify(await validateStandardSchema(out as any, { name: 'x' })));

// (3) extra keys tolerated by zod, rejected by advertised schema
console.log('(3) additionalProperties:', (j as any).additionalProperties);
console.log('(3) parse w/ extras:', JSON.stringify(out.safeParse({ name: 'x', counted: 1, sneaky: true })));

// E2E: tools/list with z.date() input
const server = new McpServer({ name: 'repro', version: '1.0.0' });
server.registerTool('t', {
    description: 'repro',
    inputSchema: { when: z.date() },
    outputSchema: { counted: z.number().default(0), name: z.string() }
}, async () => ({ content: [], structuredContent: { name: 'x' } }));
const [c2s, s2c] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: 'repro-client', version: '1.0.0' });
try {
    await Promise.all([client.connect(c2s), server.connect(s2c)]);
    await client.listTools();
} catch (e) { console.log('listTools THROWS:', (e as Error).message); }

output:

(1) THROWS: Date cannot be represented in JSON Schema
(2) output json: {"$schema":"...","type":"object","properties":{"counted":{"default":0,"type":"number"},"name":{"type":"string"}},"required":["counted","name"],"additionalProperties":false}
(2b) SDK validate({name:"x"}): {"success":true,"data":{"counted":0,"name":"x"}}
(3) additionalProperties: false
(3) parse w/ extras: {"success":true,"data":{"counted":1,"name":"x"}}
listTools THROWS: Date cannot be represented in JSON Schema

repro2.ts — SDK client rejects the SDK server's own structuredContent

import * as z from 'zod/v4';
import { InMemoryTransport } from '@modelcontextprotocol/core-internal';
import { McpServer } from '@modelcontextprotocol/server';
import { Client } from '@modelcontextprotocol/client';

const server = new McpServer({ name: 'repro', version: '1.0.0' });
server.registerTool('echo', {
    description: 'omits counted, returns extra key',
    inputSchema: {},
    outputSchema: { counted: z.number().default(0), name: z.string() }
}, async () => ({ content: [], structuredContent: { name: 'x', sneaky: true } as any }));

const [c2s, s2c] = InMemoryTransport.createLinkedPair();
const client = new Client({ name: 'repro-client', version: '1.0.0' });
await Promise.all([client.connect(c2s), server.connect(s2c)]);
console.log(JSON.stringify(await client.callTool({ name: 'echo', arguments: {} }), null, 2));

output:

ProtocolError: Structured content does not match the tool's output schema:
data must have required property 'counted', data must NOT have additional properties
    at Client.callTool (packages/client/dist/index.mjs:3885)

server's zod validate accepts the payload (fills default, drops extras), then ships the raw pre-parse object; client re-validates with ajv against the advertised schema and rejects. no third-party client needed to see the mismatch.

code path

• primary: packages/core-internal/src/util/standardSchema.ts:182 — result = std.jsonSchema[io]({ target: 'draft-2020-12' }). no way to influence zod's per-node output; must post-process.
• fallback (zod 4.0–4.1): standardSchema.ts:201 — z.toJSONSchema(schema, { target: 'draft-2020-12', io }). same hardcoded options.
• server ship path: packages/server/src/server/mcp.ts:315 runs validateStandardSchema(tool.outputSchema, result.structuredContent) (uses parseResult.success but not parseResult.data), so structuredContent is shipped as returned.
• client validate path: packages/client/dist/index.mjs:3885 ajv-validates the received structuredContent against the advertised schema and throws -32602.
• v1.x: src/server/zod-json-schema-compat.ts:34 — same pattern (z4mini.toJSONSchema with only target/io); backport needed.

suggested fix

pass libraryOptions through both conversion paths so zod's per-node override hook plus unrepresentable:'any' do the wire-shape work. non-zod libraries ignore libraryOptions by spec, so this stays scoped to the reported vendor. contained to packages/core-internal/src/util/standardSchema.ts.

// packages/core-internal/src/util/standardSchema.ts
+function makeZodLibraryOptions(io: 'input' | 'output') {
+    return {
+        unrepresentable: 'any' as const,
+        override(ctx: { zodSchema: unknown; jsonSchema: Record<string, unknown> }) {
+            const def = (ctx.zodSchema as any)?._zod?.def;
+            if (!def) return;
+            if (def.type === 'date') {
+                for (const k of Object.keys(ctx.jsonSchema)) delete ctx.jsonSchema[k];
+                ctx.jsonSchema.type = 'string';
+                ctx.jsonSchema.format = 'date-time';
+                return;
+            }
+            if (io !== 'output' || def.type !== 'object') return;
+            const isStrict = def.catchall?._zod?.def?.type === 'never';
+            if (!isStrict && ctx.jsonSchema.additionalProperties === false) {
+                delete ctx.jsonSchema.additionalProperties;
+            }
+            const props = ctx.jsonSchema.properties as Record<string, Record<string, unknown>> | undefined;
+            const required = ctx.jsonSchema.required as string[] | undefined;
+            if (props && Array.isArray(required)) {
+                const filtered = required.filter(n => props[n]?.default === undefined);
+                if (filtered.length !== required.length) {
+                    if (filtered.length === 0) delete ctx.jsonSchema.required;
+                    else ctx.jsonSchema.required = filtered;
+                }
+            }
+        }
+    };
+}
 // ...
-        result = std.jsonSchema[io]({ target: 'draft-2020-12' });
+        result = std.jsonSchema[io]({ target: 'draft-2020-12', libraryOptions: makeZodLibraryOptions(io) });
 // ...
-        result = z.toJSONSchema(schema as unknown as z.ZodType, { target: 'draft-2020-12', io }) as Record<string, unknown>;
+        result = z.toJSONSchema(schema as unknown as z.ZodType, {
+            target: 'draft-2020-12', io, ...makeZodLibraryOptions(io)
+        }) as Record<string, unknown>;

• unrepresentable:'any' stops the ZodDate throw; the override rewrites it in place so JSON.stringify(new Date(...)) (ISO-8601) satisfies the advertised schema.
• for io:'output' object nodes: drop additionalProperties:false only when the node isn't strict (never catchall), and drop .default(...)-carrying property names from required. matches what the server actually ships (pre-parse structuredContent).
• non-zod libraries ignore libraryOptions per the standard-schema spec, so no cross-vendor behavior change.

test to verify: schema-level asserts on standardSchemaToJsonSchema — z.date rewrites to string+date-time on both io modes, defaulted output fields drop out of required, plain z.object outputs lose additionalProperties:false, and z.strictObject keeps it. full core-internal + server suites (1774 tests) pass.

same shape needs to land on v1.x's src/server/zod-json-schema-compat.ts where z4mini.toJSONSchema is called with only target+io.