Skip to content

Instantly share code, notes, and snippets.

@gogakoreli
Last active October 5, 2026 18:53
Show Gist options
  • Select an option

  • Save gogakoreli/cc01c92218b5661ee4d20245119b5172 to your computer and use it in GitHub Desktop.

Select an option

Save gogakoreli/cc01c92218b5661ee4d20245119b5172 to your computer and use it in GitHub Desktop.
typescript-sdk PR #1563: local $ref inlining in tool inputSchema — investigation, evidence, decisions

PR #1563 — local $ref inlining in tool inputSchema: investigation log

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.


0. Current status

  • Assignee / active reviewer: @KKonstantinov. He self-assigned on 2026-09-12 and triggered the latest @claude review round.
  • 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 of 86c30bbd). CI was green at 86c30bbd.

1. Design decisions (settled)

# 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

2. Review history (each automated pass is fresh and doesn't carry over earlier resolutions)

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

3. 2026-09-12 findings: evidence and verdicts

Reproductions run real Zod 4.3.6 output and hand-built JSON Schema through standardSchemaToJsonSchema / dereferenceLocalRefs at the PR head.

F3: $defs: null crashes tools/list → FIXED

  • Repro (before the fix): dereferenceLocalRefs({type:'object', properties:{x:{$ref:'#/$defs/X'}}, $defs:null}) throws TypeError: 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 $defs and definitions.

F1: unresolved local $ref left dangling after the containers are stripped → FIXED

  • Before the fix:
    • {$ref:'#/$defs/Foo/properties/bar'} stayed as-is, but $defs was stripped, leaving the ref dangling.
    • With both $defs and definitions present, #/definitions/X stayed 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 ~1 and ~0, so the raw name a/b appears as #/$defs/a~1b.
  • Fix: if any fragment-only $ref other than # survives, both original containers are re-attached verbatim, so every surviving ref resolves exactly as it did in the input. Def lookup also uses Object.hasOwn, so names like constructor don't match built-in object properties.
  • Proof: the tests compile both input and output with new Ajv2020().compile(), which throws MissingRefError on a dangling ref. All 6 new tests fail on 290ebc6d and pass on 07bd75da / 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'] } loses Base.id.
  • Spec: JSON Schema 2020-12 §8.2.3.1 says $ref applies 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_siblings uses the same override semantics (merged.update(siblings), "local siblings take precedence").
  • Decision: a combining merge (allOf, or a deep merge of properties/required) adds complexity for output no supported library produces. The override semantics are documented in a code comment instead.

F4: output grows with fan-out (N^D) → DEFERRED (#1847)

  • Observed:

    Schema Without this PR With this PR
    .meta({id}) types, 4×4×4 fan-out 701 B (one $defs copy 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 $defs and composition-keyword expansion on the validator side.
  • Decision: a size cap is a reasonable follow-up, implemented inside dereferenceLocalRefs as 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".

4. Authoritative references

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

5. Known, accepted limitations

  • A root self-reference $ref: "#" stays as-is. It still resolves after inlining, and Zod emits it for root-level recursion.
  • Boolean $defs entries drop sibling keywords (D6).
  • Override sibling merge (F2 / D5).
  • No size cap yet (F4: a budget inside dereferenceLocalRefs, follow-up).
  • outputSchema is not dereferenced (§6): out of scope; it's consumed by validators, not filled by LLMs.

6. Verification

At 86c30bbd (rebased onto origin/main@b0225220, 49 upstream commits)

  • Rebase applied cleanly with no conflicts. The PR's own +/- lines are byte-identical to before the rebase (7 files).

  • pnpm build:all and pnpm check:all (typecheck + lint) are clean.

  • Tests:

    Package Result
    core-internal 1545/1545
    server 576/576
    client 997/997
    codemod 645/645
    server-legacy 181/181
    express / hono / fastify 45 / 18 / 23
    test/integration 379/379
    server conformance 73/73, baseline check passed
  • Failures not caused by this PR: the same tests fail on plain origin/main@b0225220 locally (Node 26, macOS):

    • middleware/node streamableHttp.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)

Upstream interactions, cross-validated end to end

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/list convertListedInputSchema() → standardSchemaToJsonSchema(…, 'input') → dereferenceLocalRefs
    Pre-dispatch SEP-2243 validation createMcpHandler → McpServer.toolInputSchemaJson() → same function, memoized per instance
    Elicitation elicitation.ts → same function
    Prompts (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/list is not memoized after #2889, so dereferencing runs once per tool on every tools/list. Measured (Bun, M-series):

    Schema dereferenceLocalRefs Zod 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 inside dereferenceLocalRefs, 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 properties keys … MUST NOT pass through … $ref. Nested object properties are permitted." The advertised (inlined) schema has the chain properties.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 main silently 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 with x-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 $defs and remains invalid, the same as main.

outputSchema is not dereferenced (verified in code and end to end)

  • standardSchemaToJsonSchema returns from the io === 'output' branch (SEP-2106 root handling) before reaching dereferenceLocalRefs. The PR has always hooked only the input/object path; that branch was already in b6542615.
  • An earlier bot note claimed "input and output schemas are inlined symmetrically". That claim is wrong. Output schemas keep $ref + $defs, the same as main.
  • Leaving it out is reasonable: outputSchema is 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 an id key inside the emitted schema. The SDK client's Ajv then refuses to compile such an outputSchema ("NOT SUPPORTED: keyword "id", use "$id""), and callTool fails with -32602. Worth a separate upstream issue.

At 07bd75da (before the rebase)

  • core-internal: 1477/1477, typecheck and lint clean
  • server: 482/482
  • test/integration: 376/376 (includes the 5 end-to-end $ref pipeline tests)
  • New tests: 6, each failing before the fix and passing after

7. Further cross-validation (round 3, at 86c30bbd)

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.

7.1 All three Standard-Schema libraries

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 $ref with $defs beside 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.

7.2 Zod version matrix (SDK range zod ≥ 4.0)

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.

7.3 Related issue #2100 ("reused Zod instances emit $ref, Kimi rejects")

  • The refs reported there are #/properties/... back-pointers from zod-to-json-schema with $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.ts on v1.x). On v2, reused unregistered instances emit no $ref on 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 } of standardSchemaToJsonSchema. 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, then dereferenceLocalRefs(...).
  • #2556's stripLegacyIdKeywords removes the zod .meta({id}) → id keyword that Ajv v8 rejects at compile time. That's the fix for the outputSchema / id callTool failure noted in §6, so no separate issue is needed. After both land, inlined defs carry no id.
  • 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 });

7.5 What LLM providers actually document about $ref

  • OpenAI documents $ref support, but only along a specific chain. Quotes from the docs fetched 2026-10:
    1. Function calling → Defining functions: parameters is "JSON schema … you can leverage many of its rich features like … nested objects, and recursive objects."
    2. Function calling → Strict mode: "strict mode works by leveraging our structured outputs feature", and the schema must fit the "supported schemas" subset.
    3. 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: false on every object and every field required. 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 $ref guarantee for best-effort mode.
      • Whether the $ref reaches OpenAI intact depends on the MCP client in between.
      • Not tested against the live API (that would mean sending data to a third party).
    • Limits from the same page: ≤ 5000 object properties total, ≤ 10 nesting levels, ≤ 120,000 characters across names and enum values.
  • Moonshot / Kimi: rejects any $ref not starting with #/$defs/ ("references must start with #/$defs/"), per ms-365-mcp-server#458.
  • Claude Code anthropics/claude-code#18260: $ref parameters 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 $ref and 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 $defs form wouldn't.

7.6 Robustness edge cases (likely future bot findings)

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

8. Merge-readiness: things to settle before the next review round

  1. Coordinate with #2556: not pursued (author decision; #2556 may never merge). If it does land first, rebase and apply 7.4.
  2. Fix the wording: done in 6a0701d0 and the PR description (7.5).
  3. Optional cheap hardening: own-property assignment in the walker (__proto__, 7.6). It's the most likely next "new finding".
  4. Docs: docs/advanced/schema-libraries.md doesn't say that tool inputSchema local refs are inlined and that fromJsonSchema passes through verbatim. docs/behavior-surface-pins.md asks for docs where a change is consumer-facing. One sentence would pre-empt a "where is this documented?" round.
  5. Settle scope explicitly with the assignee: F2 (override merge) and F4 (size budget) are follow-ups, outputSchema is out of scope, and #2100 is v1.x. Getting that agreed up front stops automated rounds from reopening them.
  6. Review state: @KKonstantinov is assignee; @felixweinberger's stale CHANGES_REQUESTED needs a re-review or dismissal.
  7. 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment