PR: modelcontextprotocol/typescript-sdk#1563 · Issue: #1562 · Follow-up: #1847 (convert at registerTool time)
This doc collects the decisions on PR #1563, the evidence behind them, and the sources checked, so review rounds don't reopen settled questions. Each finding below records the verdict, how it was reproduced, and the external references.
Environment for the evidence below: PR head 290ebc6d → 07bd75da, rebased onto origin/main@b0225220 as 86c30bbd (patch byte-identical), zod 4.3.6, Ajv 2020 (ajv/dist/2020.js), Node 26.
- Assignee / active reviewer: @KKonstantinov. He self-assigned on 2026-09-12 and triggered the latest
@claude reviewround. - Merge blocker: a stale CHANGES_REQUESTED review from @felixweinberger (2026-04-02). What it asked for, best-effort inlining (D2), landed right after. It needs a re-review or a dismissal.
- Head:
6a0701d0(changeset text only on top of86c30bbd). CI was green at86c30bbd.
| # | Decision | Decided in | Rationale |
|---|---|---|---|
| D1 | Hook into standardSchemaToJsonSchema(), not Zod-specific code |
Felix, 2026-03-27 | Covers Zod / ArkType / Valibot and every consumer (tools, prompts, elicitation) |
| D2 | Graceful degradation on cycles (not throw, not {type:"object"}) |
Felix, 2026-04-02 | Throwing breaks servers with z.lazy() schemas that work today. Non-cyclic refs are fully inlined; for cyclic ones the $ref stays and only those $defs entries are kept, matching fastmcp's best-effort approach |
| D3 | fromJsonSchema() (vendor 'mcp') passes through verbatim |
2026-08-26, conformance json-schema-2020-12 / SEP-1613 |
A hand-written $ref is intentional and must survive tools/list unchanged. Only library-produced $ref (a conversion side effect) is inlined |
| D4 | Never worse than the untransformed schema | 2026-09 (this round) | Inputs that can't be fully resolved must not produce a schema that's broken where the original was valid |
| D5 | Sibling merge uses override semantics (siblings win) | This round | Matches fastmcp, and Zod only emits annotation siblings (see F2) |
| D6 | Boolean $defs entries skip the sibling merge |
2026-04-12 | JsonSchemaType excludes boolean schemas, and no library emits them in $defs |
| Round | Source | Findings | Status |
|---|---|---|---|
| 2026-03-27 | Felix | rebase onto standardSchema, throw on cycles | done; later reversed by D2 |
| 2026-04-01 | claude[bot] ×3 | nested $ref in siblings, $defs leaking via the sibling merge, a property named $defs/definitions being dropped |
fixed (root-only strip, siblings resolved) |
| 2026-04-02 | Felix | best-effort inlining instead of throwing | done (D2) |
| 2026-04-09 | claude[bot] ×2 | boolean $defs sibling drop, outdated changeset |
documented (D6) / fixed |
| 2026-08-26 | CI conformance | json-schema-2020-12 failure |
fixed (D3) |
| 2026-09-12 | claude[bot] ×4 (triggered by @KKonstantinov, who self-assigned the PR the same day), all "🟡 optional / nit, nothing blocking" | F1–F4 below | F1, F3 fixed in 07bd75da (now 86c30bbd after rebase); F2, F4 answered below |
Reproductions run real Zod 4.3.6 output and hand-built JSON Schema through standardSchemaToJsonSchema / dereferenceLocalRefs at the PR head.
- Repro (before the fix):
dereferenceLocalRefs({type:'object', properties:{x:{$ref:'#/$defs/X'}}, $defs:null})throwsTypeError: null is not an object (evaluating 'defs[defName]'). One malformed tool fails the whole list; without this PR the schema was passed through unchanged. - Fix: if the container is null, an array or a primitive, the schema is returned untouched (
toBe(schema)), for both$defsanddefinitions.
- Before the fix:
{$ref:'#/$defs/Foo/properties/bar'}stayed as-is, but$defswas stripped, leaving the ref dangling.- With both
$defsanddefinitionspresent,#/definitions/Xstayed as-is, but both containers were stripped, leaving it dangling.
- Zod never emits these forms (it uses bare
#/$defs/Name, or#for a root self-reference). The fix is still cheap, and D4 requires it. - Spec basis:
- JSON Schema 2020-12 §5 / §9.2.1: a fragment can be any JSON Pointer, not just
#/$defs/<name>. - RFC 6901 §3–4:
/and~inside a name are escaped as~1and~0, so the raw namea/bappears as#/$defs/a~1b.
- JSON Schema 2020-12 §5 / §9.2.1: a fragment can be any JSON Pointer, not just
- Fix: if any fragment-only
$refother than#survives, both original containers are re-attached verbatim, so every surviving ref resolves exactly as it did in the input. Def lookup also usesObject.hasOwn, so names likeconstructordon't match built-in object properties. - Proof: the tests compile both input and output with
new Ajv2020().compile(), which throwsMissingRefErroron a dangling ref. All 6 new tests fail on290ebc6dand pass on07bd75da/86c30bbd.
F2: structural siblings next to $ref overwrite the def's properties/required → DECLINED (documented)
- Mechanism confirmed with hand-built input:
{ $ref:'#/$defs/Base', properties:{extra}, required:['extra'] }losesBase.id. - Spec: JSON Schema 2020-12 §8.2.3.1 says
$refapplies the referenced schema and that other keywords can appear alongside it. Strictly, both apply (they combine). - Supported libraries never emit this shape (Zod 4.3.6, observed):
Base.describe('d')emits{description:'d', $ref}Base.default(v)emits{default:v, $ref}Base.meta({title})emits{title, $ref}Base.extend({...})emits a flat inlined object with no$ref
- Prior art: fastmcp's
_merge_ref_siblingsuses the same override semantics (merged.update(siblings), "local siblings take precedence"). - Decision: a combining merge (
allOf, or a deep merge ofproperties/required) adds complexity for output no supported library produces. The override semantics are documented in a code comment instead.
-
Observed:
Schema Without this PR With this PR .meta({id})types, 4×4×4 fan-out701 B (one $defscopy per type)8,742 B Same graph without ids (Zod default reused:'inline')7,966 B (Zod inlines it already) 7,966 B -
So inlined size is the same as Zod's own default output. The growth only affects users of registered ids.
-
Prior art:
- fastmcp does bound it (
_MAX_INLINED_NODES=100_000,_MAX_INLINED_DEPTH=128,_MAX_INLINED_TEXT=5_000_000) and falls back to the original refs when over budget. - MCP spec, "Composition-Keyword Resource Use": implementations SHOULD bound
$defsand composition-keyword expansion on the validator side.
- fastmcp does bound it (
-
Decision: a size cap is a reasonable follow-up, implemented inside
dereferenceLocalRefsas a budget with a fallback to the original refs (fastmcp-style), so it doesn't depend on when conversion runs.It belongs with #1847: corrected after the rebase, because #2889 moved conversion away from registration time (see §6). Not done here; the bot itself noted a cap "conflicts with stated purpose".
| Source | What it establishes |
|---|---|
| JSON Schema 2020-12 Core §8.2.3.1 | $ref is an applicator; adjacent keywords are allowed and also apply |
| JSON Schema 2020-12 Core §8.2.4 | $defs is a reserved location and doesn't itself affect validation, so removing unused entries is safe |
| JSON Schema 2020-12 Core §9.2.1 | JSON Pointer fragments can point anywhere in the document |
| RFC 6901 §3–4 | ~0 / ~1 escaping in pointer tokens |
| MCP spec: JSON Schema Usage | Default dialect is 2020-12. MUST NOT auto-fetch network $ref (this PR only touches local refs). SHOULD bound $defs / composition expansion |
| MCP spec: Tool | inputSchema MUST be a valid JSON Schema object; no rule forbids or requires inlining |
Zod: JSON Schema (cycles, reused, Registries) |
Cycles produce $ref (# or a $defs entry). reused defaults to "inline". Registered ids always produce $ref |
fastmcp json_schema.py @ 5baeacf |
Reference implementation Felix linked: best-effort inlining, falls back to the original refs on cycles or over budget, override sibling merge, strips $defs only when fully inlined |
- A root self-reference
$ref: "#"stays as-is. It still resolves after inlining, and Zod emits it for root-level recursion. - Boolean
$defsentries drop sibling keywords (D6). - Override sibling merge (F2 / D5).
- No size cap yet (F4: a budget inside
dereferenceLocalRefs, follow-up). outputSchemais not dereferenced (§6): out of scope; it's consumed by validators, not filled by LLMs.
-
Rebase applied cleanly with no conflicts. The PR's own
+/-lines are byte-identical to before the rebase (7 files). -
pnpm build:allandpnpm check:all(typecheck + lint) are clean. -
Tests:
Package Result core-internal1545/1545 server576/576 client997/997 codemod645/645 server-legacy181/181 express / hono / fastify 45 / 18 / 23 test/integration379/379 server conformance 73/73, baseline check passed -
Failures not caused by this PR: the same tests fail on plain
origin/main@b0225220locally (Node 26, macOS):middleware/nodestreamableHttp.test.ts: 2 SSE tests ("batch request messages with SSE stream", "store and replay … notifications")test/e2e: 8[sse …]scenarios (progress callback / token-injected,tools:call:progress,timeout:max-total)
Method: a temporary integration test (not committed) runs a real Client (pinned to 2026-07-28) → StreamableHTTPClientTransport → toNodeHandler(createMcpHandler(factory)) over real HTTP. The same file ran against plain origin/main@b0225220 and against the PR (86c30bbd).
#2889 "convert tool schemas on demand, not at registration" (4d94e7b1, co-authored by Felix)
-
Code paths at the PR head, each confirmed by reading the code:
Path Route tools/listconvertListedInputSchema()→standardSchemaToJsonSchema(…, 'input')→dereferenceLocalRefsPre-dispatch SEP-2243 validation createMcpHandler→McpServer.toolInputSchemaJson()→ same function, memoized per instanceElicitation elicitation.ts→ same functionPrompts ( promptArgumentsFromStandardSchema)same function This PR's hook point is unchanged, so the advertised schema and the server's validation schema are identical by construction.
-
Cost:
tools/listis not memoized after #2889, so dereferencing runs once per tool on everytools/list. Measured (Bun, M-series):Schema dereferenceLocalRefsZod conversion alone typical registered-type schema ~1.1 µs ~4.1 µs 4×4×4 fan-out ~3.5 µs ~7.9 µs Negligible next to conversion.
-
⚠️ Correction: I had suggested doing the F4 size cap together with #1847 ("convert eagerly at register time"). #2889 went the other way on purpose: a server built per request would otherwise convert every tool on every request. A size cap therefore belongs insidedereferenceLocalRefs, as a budget with a fallback to the original refs like fastmcp's_MAX_INLINED_*, independent of when conversion runs.
SEP-2243 x-mcp-header on a field of a registered type: tool input z.object({ region: Region, q }), where Region = z.object({ code: z.string().meta({'x-mcp-header':'Region'}) }).meta({ id }).
| Observed over real HTTP | main (no PR) |
PR |
|---|---|---|
Server tools/list warning |
"invalid x-mcp-header … <$defs>.code … not … $ref" |
none |
Client tools/list |
tool excluded (the spec's client MUST) | tool listed; region inlined, no $defs |
Client tools/call headers |
no Mcp-Param-* |
mcp-param-region: us-west1 |
Forged mismatching Mcp-Param-Region |
200, not validated | 400 / -32020 HeaderMismatch (region.code) |
Top-level x-mcp-header tool |
works | works (unchanged) |
- Spec check (Streamable HTTP, Custom Headers from Tool Parameters): a header is valid only on a property "reachable via a chain consisting solely of
propertieskeys … MUST NOT pass through …$ref. Nested object properties are permitted." The advertised (inlined) schema has the chainproperties.region.properties.code, so it's valid. Client and server read the same advertised schema and agree. - So this is a behavior change, not just a side improvement. Tools that
mainsilently made unusable on modern HTTP clients now work, and their header values are now mirrored. The spec warns header values are visible to intermediaries, but that only applies where the author opted in withx-mcp-header. Server-side enforcement now also applies to these tools: a client that ignores the annotation gets 400 for a missing header, exactly as it already does for top-level headers. A header inside a cyclic def stays under$defsand remains invalid, the same asmain.
outputSchema is not dereferenced (verified in code and end to end)
standardSchemaToJsonSchemareturns from theio === 'output'branch (SEP-2106 root handling) before reachingdereferenceLocalRefs. The PR has always hooked only the input/object path; that branch was already inb6542615.- An earlier bot note claimed "input and output schemas are inlined symmetrically". That claim is wrong. Output schemas keep
$ref+$defs, the same asmain. - Leaving it out is reasonable:
outputSchemais consumed by validators (Ajv resolves local$ref), not filled in by an LLM, and the SEP-2106 legacy wrap depends on the root. It's called out here so it isn't mistaken for a bug later. - Pre-existing and not caused by this PR (same on
main): Zod.meta({ id })puts anidkey inside the emitted schema. The SDK client's Ajv then refuses to compile such anoutputSchema("NOT SUPPORTED: keyword "id", use "$id""), andcallToolfails with -32602. Worth a separate upstream issue.
core-internal: 1477/1477, typecheck and lint cleanserver: 482/482test/integration: 376/376 (includes the 5 end-to-end$refpipeline tests)- New tests: 6, each failing before the fix and passing after
All probes ran against the PR head using the repo's own pinned libraries: zod 4.3.6, arktype 2.2.0, valibot 1.3.1 with @valibot/to-json-schema 1.6.0, and Ajv 2020. The probe scripts were temporary and are not committed.
| Library / shape | Raw library output | Advertised by PR | Ajv agreement (raw vs advertised vs the library's own parse) |
|---|---|---|---|
| zod: reused unregistered instance | no $ref (Zod's default reused:'inline') |
unchanged | n/a |
zod: reused .meta({id}) + .describe() |
$ref + description sibling |
inlined; sibling kept | Ajv rejects both (id keyword, pre-existing; see 7.4) |
| zod: non-root recursion / mutual recursion | #/$defs/__schema0 |
cyclic $ref + that def kept |
✅ |
| zod: root self-recursion | $ref: "#", no $defs |
unchanged (# still resolves) |
✅ |
| arktype: reused object | no $ref |
unchanged | ✅ |
arktype: recursive scope() |
root-level $ref + $defs + $schema siblings |
root inlined; only the cyclic def kept | ✅ 5/5 samples agree with arktype's own validation |
| valibot: reused object | no $ref |
unchanged | ✅ |
valibot: v.lazy recursion |
#/$defs/0 |
first occurrence inlined, cyclic def kept | ✅ 3/3 samples agree with v.safeParse |
- ArkType's recursive scope is the only real-world producer of a root
$refwith$defsbeside it, the shape an earlier bot round worried about. It's handled correctly. - Valibot def names (
0,1, …) come from a global counter in valibot, so names differ between conversions. That's not caused by this PR.
| zod | ~standard.jsonSchema |
Reused unregistered instance | Recursive type |
|---|---|---|---|
| 4.0.17 | no (SDK fallback path) | no $ref |
#/$defs/__schema0 |
| 4.1.12 | no (SDK fallback path) | no $ref |
#/$defs/__schema0 |
| 4.2.1 | yes | no $ref |
#/$defs/__schema0 |
| 4.3.6 | yes | no $ref |
#/$defs/__schema0 |
Emitted ref shapes are the same on both conversion paths and across every supported minor version.
- The refs reported there are
#/properties/...back-pointers fromzod-to-json-schemawith$refStrategy:'root'(Softeria/ms-365-mcp-server#458, which the reporter says is fixed downstream). - That's the v1.x converter path (
src/server/zod-json-schema-compat.tsonv1.x). On v2, reused unregistered instances emit no$refon every zod version in 7.2. - This PR therefore neither fixes nor claims #2100. It also leaves
#/properties/...refs untouched, because a schema with no definitions container returns early. Don't link #2100 as fixed.
7.4 Overlap with open PR #2556 (zod conversion "wire-truthful"; requested by Felix; open, REVIEW_REQUIRED, 64 commits behind main)
- A merge conflict is certain: both PRs edit the final
return { type: 'object', ...result }ofstandardSchemaToJsonSchema. Confirmed with a trial merge. - It's semantically compatible:
- #2556 treats
#/#/$defs/<name>as "zod's own registry shapes" and only changes behavior when it finds hand-authored reference constructs. - This PR runs after conversion, on the finished document.
- Merged order should be: #2556's conversion and typeless-root verdict, then this PR's
vendor === 'mcp'passthrough, thendereferenceLocalRefs(...).
- #2556 treats
- #2556's
stripLegacyIdKeywordsremoves the zod.meta({id})→idkeyword that Ajv v8 rejects at compile time. That's the fix for theoutputSchema/idcallToolfailure noted in §6, so no separate issue is needed. After both land, inlined defs carry noid. - Resolution for whichever PR lands second:
if (result.type === undefined) { /* #2556 typeless-root verdict, unchanged */ } if (std.vendor === 'mcp') return { type: 'object', ...result }; return dereferenceLocalRefs({ type: 'object', ...result });
- OpenAI documents
$refsupport, but only along a specific chain. Quotes from the docs fetched 2026-10:- Function calling → Defining functions:
parametersis "JSON schema … you can leverage many of its rich features like … nested objects, and recursive objects." - Function calling → Strict mode: "strict mode works by leveraging our structured outputs feature", and the schema must fit the "supported schemas" subset.
- Structured Outputs → Supported schemas has two sections. "Definitions are supported" shows
"items": { "$ref": "#/$defs/step" }with a root$defs. "Recursive schemas are supported" shows both"$ref": "#"and"$ref": "#/$defs/linked_list_node".
- Caveats:
- The explicit guarantee is for strict mode, which also requires
additionalProperties: falseon every object and every fieldrequired. Typical Zod MCP schemas don't meet that. - Without strict mode, Responses tries to normalize the schema and otherwise falls back to "non-strict, best-effort function calling". Chat Completions is non-strict by default. The docs make no specific
$refguarantee for best-effort mode. - Whether the
$refreaches OpenAI intact depends on the MCP client in between. - Not tested against the live API (that would mean sending data to a third party).
- The explicit guarantee is for strict mode, which also requires
- Limits from the same page: ≤ 5000 object properties total, ≤ 10 nesting levels, ≤ 120,000 characters across names and enum values.
- Function calling → Defining functions:
- Moonshot / Kimi: rejects any
$refnot starting with#/$defs/("references must start with #/$defs/"), per ms-365-mcp-server#458. - Claude Code anthropics/claude-code#18260:
$refparameters get serialized as strings. Still OPEN (9 comments), so there's no client-side fix yet. - Gemini function-declaration docs: not verified (the fetch timed out).
- ✅ Wording fixed (
6a0701d0+ PR description): "LLMs cannot resolve$ref" → "several MCP clients and model integrations mishandle or reject$ref". OpenAI strict mode has handled$refand recursion since Structured Outputs launched (announcement, 2024-08-06: a recursive sample using"$ref": "#", compiled to a context-free grammar). So the blanket claim was inaccurate even when the PR was opened (2026-02), while the client failures it cites were real then and still are. More accurate: "many MCP clients and model providers mishandle or reject$ref(Claude Code #18260, Kimi), and inlined schemas are the lowest-common-denominator form every client accepts." - OpenAI's 5000-property cap is a concrete external reason for the F4 size budget: a heavy fan-out inlined graph can exceed it where the
$defsform wouldn't.
| Case | Result | Notes |
|---|---|---|
| Input immutability | ✅ the library's returned object is not mutated | cached defs are shared by reference in the output only |
| Deep nesting (stack) | dereferenceLocalRefs overflows at ~1875 levels, zod's own conversion at ~1562 |
zod fails first, so this adds no failure mode (fastmcp caps depth at 128) |
Property named __proto__ |
Zod and Valibot already drop it in their raw output; ArkType throws "Duplicate key"; fromJsonSchema (vendor mcp) bypasses dereferencing |
Unreachable today. But the walker's result[key] = … would turn a hand-built __proto__ key into a prototype assignment and drop it. A one-line pre-emptive fix (define own properties, e.g. Object.defineProperty/Object.fromEntries) is cheap insurance against a future bot round |
| Prompt argument descriptions from a registered type | ✅ description from .meta({id, description}) survives in prompts/list on the PR |
main not compared |
Coordinate with #2556: not pursued (author decision; #2556 may never merge). If it does land first, rebase and apply 7.4.Fix the wording: done in6a0701d0and the PR description (7.5).- Optional cheap hardening: own-property assignment in the walker (
__proto__, 7.6). It's the most likely next "new finding". - Docs:
docs/advanced/schema-libraries.mddoesn't say that toolinputSchemalocal refs are inlined and thatfromJsonSchemapasses through verbatim.docs/behavior-surface-pins.mdasks for docs where a change is consumer-facing. One sentence would pre-empt a "where is this documented?" round. - Settle scope explicitly with the assignee: F2 (override merge) and F4 (size budget) are follow-ups,
outputSchemais out of scope, and #2100 is v1.x. Getting that agreed up front stops automated rounds from reopening them. - Review state: @KKonstantinov is assignee; @felixweinberger's stale CHANGES_REQUESTED needs a re-review or dismissal.
- Stale cross-reference: open PR #1861 (convert at registration time) cites "cycle detection from #1563", which no longer exists (D2). #2889 also went the other way, so #1861 is likely superseded. Not ours to fix, but don't link it as complementary.