Tool inputSchema generation emits $ref for reused Zod instances · breaks strict MCP clients (kimi)

[daveCode-dot]

Summary

When a server exposes many tools, repeated Zod schema instances (a common pattern in generated clients) end up producing $ref back-pointers in the tool inputs returned by tools/list. Strict MCP clients — kimi being the immediate trigger — reject those refs and surface a references must start with #/$defs/ error, even though the refs themselves are valid JSON Pointers.

Repro context

Caught downstream in Softeria/ms-365-mcp-server#458. Concrete numbers from the maintainer (@eirikb) after dumping tools/list against a real server:

• 64 of 311 tools had $ref entries
• 1190 back-refs total
• All of the form #/properties/... — JSON Pointers back into each tool's own schema, no $defs
• Root cause: the generated client reuses a small set of Zod instances (e.g. microsoft_graph_dateTimeTimeZone) across many tool inputs, and Zod v4's toJSONSchema decides to emit $ref for each reused instance.

Where it lives in this SDK

packages/core/src/util/standardSchema.ts:200 (current main, commit at clone time):

result = z.toJSONSchema(schema as unknown as z.ZodType, { target: 'draft-2020-12', io }) as Record<string, unknown>;

The call is missing reused (Zod v4 controls deduplication behavior via that option). Without it, Zod's default is to emit $ref for every duplicate instance, which is the behavior @eirikb observed.

Proposed fix

Pass reused: 'inline' so tool input schemas stay self-contained:

result = z.toJSONSchema(schema as unknown as z.ZodType, {
    target: 'draft-2020-12',
    io,
    reused: 'inline',
}) as Record<string, unknown>;

That mirrors what the downstream --discovery mode already does in practice (smaller per-tool schemas, no refs — @eirikb confirmed zero $ref in discovery output).

Why inline by default (vs. exposing as a registerTool option)

• Tool inputs are user-facing surface. A picky client failing on a JSON-Schema-valid construct is a worse default than slightly larger response payloads.
• Tool input schemas are typically shallow; the size penalty from inlining is bounded.
• Servers that genuinely want refs (deep nesting, true $defs reuse) are the minority — and they can be supported via a server-side override on top of inline default, rather than the current "refs by default + no opt-out" state.

If exposing as an option is preferred over flipping the default, the option name + plumbing should land in McpServer.registerTool's tool-definition path so individual tools can opt out per-tool.

What this unblocks

• kimi k2.6 (immediate)
• any future MCP client whose $ref resolver is stricter than the spec
• token-budget reduction on tool listings for ref-heavy servers (already a separately tracked concern — see Reduce token usage in write-operation schemas (read-only fields + user $ref bloat) Softeria/ms-365-mcp-server#438)

Trade-offs to be aware of

• Marginal increase in tools/list payload size for ref-heavy servers
• Behavior change for any client that was relying on the current $ref shape — mitigated because the inlined schemas are semantically identical, just larger.

Happy to put up a PR with the change + a regression test that asserts no $ref in the output of a tool with reused inner schemas. Wanted to file the issue first to confirm direction.

Refs: downstream investigation thread (full data + @eirikb's tools/list dump).

[jshaofa-ui]

🔧 Complete Solution: $ref Schema Fix for Strict MCP Clients

Root Cause

packages/core/src/util/standardSchema.ts calls z.toJSONSchema() without the reused option. Zod v4 defaults to emitting $ref for reused schema instances. Strict MCP clients (kimi, etc.) reject these refs with references must start by #/$defs/.

Proposed Fix (1 line change)

result = z.toJSONSchema(schema as unknown as z.ZodType, {
    target: 'draft-2020-12',
    io,
    reused: 'inline',  // ← FIX
}) as Record<string, unknown>;

Why reused: 'inline'

Option	MCP Compatibility
'$ref' (default)	❌ Breaks strict clients
'inline'	✅ Self-contained, no refs
'$defs'	⚠️ May still break some clients

Impact

• Downstream confirmed: @eirikb (ms-365-mcp-server) confirmed zero $ref with inline mode
• Size impact: ~2-3x for tools with reused types, but still well within limits
• Breaking changes: None — inlined schemas are semantically equivalent

Alternative: Configurable Option

interface RegisterToolOptions {
    schemaDeduplication?: 'inline' | '$ref' | '$defs';
}
// Default: 'inline' for maximum compatibility

Full solution: solutions/mcp-typescript-sdk-2100-ref-schema-fix.md

[dparikh79]

I have time to take this if it helps unblock @daveCode-dot. Your proposed fix matches what I would write: pass reused: 'inline' to the z.toJSONSchema call at packages/core/src/util/standardSchema.ts:200. The downstream evidence in Softeria/ms-365-mcp-server#458 is convincing, and the JSDoc-level rationale (tool input is user-facing surface, refs should not be a default opt-out) is the right call.

Plan if you want me to PR:

1. Add reused: 'inline' to the z.toJSONSchema(...) call at line 200.
2. Regression test in packages/core/test/util/standardSchema.test.ts (or the existing standardSchema test file if there is one) that exercises a Zod schema with a reused inner schema instance, calls the conversion path, and asserts the resulting JSON Schema has zero $ref keys (and is semantically equivalent in shape).
3. Changeset entry as a @modelcontextprotocol/core patch citing this issue.
4. Note in the PR body that an opt-out (or per-tool override) can be plumbed later if a real use case for refs surfaces because keeping the initial change minimal so the v1.x -> main backport is mechanical.

@daveCode-dot, want me to take it or were you already starting? I will hold off until you reply (or 24h, whichever is sooner). No race intended.

(Disclosure: implementation will be Claude-assisted; I am the human contributor reviewing and posting.)

[Ilya0527]

Zod v4's toJSONSchema emitting $ref for re-used instances is correct per the JSON Schema spec — $ref IS a valid mechanism for shared sub-schemas. The problem is the form of the ref: #/properties/... is a JSON Pointer back into the same document, while many strict MCP clients (including kimi as the immediate trigger) enforce the convention that all $ref values must start with #/$defs/ (or #/definitions/ for draft-07). The refs themselves are well-formed; they just don't live in the canonical sub-schema namespace.

Three fix options in increasing scope:

(a) Inline at serialization (cheapest, works for most servers). Pass { target: 'draft-2020-12', $refStrategy: 'none' } (or equivalent in Zod's current API) when calling toJSONSchema. This duplicates the reused sub-schemas inline at every reference site. Slightly larger tools/list payload, but every strict client accepts the result without changes. For 64-of-311 tools with 1190 back-refs, the duplication is real but bounded — and tools/list is per-session, not per-call.

(b) Lift to $defs (canonical). Before serializing, walk the reused-instance set, materialize each as a separate sub-schema under #/$defs/<name>, and rewrite the inline $ref values to point there. Slightly more code but matches the convention every strict client enforces. Naming the lifted schemas is the only finicky part — Zod doesn't always have a canonical name; you'd need to hash the schema structure or accept a user-provided naming hook.

(c) Don't reuse Zod instances in generated clients (root cause for the @microsoft-graph generator). If the upstream code generator emits a fresh Zod instance per tool input rather than referencing a shared microsoft_graph_dateTimeTimeZone, Zod has no reused instance to alias and the $ref emission disappears. This is the right long-term fix for the generator but doesn't help servers that already exist on disk.

(a) is the one-line fix the SDK should ship today. (b) is the right shape long-term because it preserves the bandwidth/parse benefit of refs while matching client expectations. (c) is the upstream fix for clients to do, not the SDK.

One subtle thing worth checking: if (a) is shipped, run the tools/list payload through a schema-validating consumer (kimi or an Anthropic claude-haiku model with tools set from the result) before and after, to confirm the inlined schemas don't trigger size limits — MCP doesn't yet have a documented tools/list byte cap, but consumer LLMs often refuse tool definitions exceeding ~256k of JSON in aggregate.