You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Absolute URI (e.g., https://example.com/schema.json#/defs/DateTime)
Fragment-only reference starting with #/$defs/ (e.g., #/$defs/DateTime)
The error "references must start with #/$defs/>" suggests your schema is generating $ref values that don't match either pattern. This likely occurs when:
Schema objects are being serialized without resolving relative paths to the root definition anchor
The Moonshot API's validation is stricter about ref format than other LLM providers
Have you checked whether the Graph API schemas are using relative $ref paths that need to be resolved to absolute or fragment-only format before passing to Moonshot?
Ok so I dug into this a bit. ran the server locally and dumped tools/list: 64 of 311 tools have $refs (1190 of them), and they all look like #/properties/..., just JSON Pointers back into the same tool's own schema. no $defs, no definitions, nothing.
So the refs aren't actually wrong, fragment-only pointers are perfectly fine JSON Schema. kimi is just being picky.
Reason they show up: the generated client reuses the same zod instances everywhere (microsoft_graph_dateTimeTimeZone and friends), and the mcp sdk runs them through zod-to-json-schema without setting $refStrategy or target, so it falls back to 'root' + jsonSchema7 and back-refs every duplicate.
Real fix is in the typescript-sdk, they should either expose $refStrategy or just default tool inputs to 'none'. probably worth poking them about it.
Anyway, --discovery is still the move for now, confirmed zero $refs there.
@eirikb thanks for the deep dive — that's the real root cause, not the surface "refs are malformed" interpretation I went on first.
I checked modelcontextprotocol/typescript-sdk and there's no open or closed issue about exposing $refStrategy / changing the zod-to-json-schema default for tool inputs. That's a clean gap. Happy to open one upstream citing your analysis (64/311 tools, 1190 back-refs, root strategy fallback, kimi rejection) unless you prefer to file it yourself — your repro is concrete enough to act on directly.
Worth noting: remove-recursive-refs.js already in this repo explicitly disclaims it won't help "if the tool still struggles with $ref in general" — which is exactly the kimi case. So kimi falls outside what that helper is scoped to fix.
For now --discovery is the move (confirmed). Long term, the typescript-sdk patch is the right place. Ping me if you want me to draft the upstream issue.
Quick recap of what's in the issue, sourced from your dump + a look at the SDK source:
The relevant line is packages/core/src/util/standardSchema.ts:200, where z.toJSONSchema is called without reused. That's the knob that controls whether duplicates get $ref'd or inlined.
Proposed fix: pass reused: 'inline'. That matches what --discovery mode already produces in practice (no refs).
Argued for inline-by-default over an opt-in option, since the alternative (server can't override the picky-client default) is the worse failure mode.
Offered to put up the PR with a regression test that asserts no $ref in the output of a tool with reused inner schemas. Will wait for upstream direction before pushing code.
Thanks for the dump — having 64/311 · 1190 refs in hand made the issue concrete instead of speculative.
Activity
eirikb commentedon May 12, 2026
I believe this is a upstream issue in the modelcontextprotocol sdk.
We can solve this on our side by hacking the spec on the way out - buuuuut I don't think that is a very good solution.
If you open an issue on https://github.com/modelcontextprotocol/typescript-sdk that might help.
What you can do is to try
--discovery, since you then only get three tools with simple params (no $refs).daveCode-dot commentedon May 14, 2026
Per the JSON Schema specification (https://json-schema.org/draft/2020-12/schema), $ref references must either:
https://example.com/schema.json#/defs/DateTime)#/$defs/(e.g.,#/$defs/DateTime)The error "references must start with #/$defs/>" suggests your schema is generating $ref values that don't match either pattern. This likely occurs when:
Have you checked whether the Graph API schemas are using relative $ref paths that need to be resolved to absolute or fragment-only format before passing to Moonshot?
eirikb commentedon May 14, 2026
Ok so I dug into this a bit. ran the server locally and dumped tools/list: 64 of 311 tools have $refs (1190 of them), and they all look like
#/properties/..., just JSON Pointers back into the same tool's own schema. no$defs, nodefinitions, nothing.So the refs aren't actually wrong, fragment-only pointers are perfectly fine JSON Schema. kimi is just being picky.
Reason they show up: the generated client reuses the same zod instances everywhere (
microsoft_graph_dateTimeTimeZoneand friends), and the mcp sdk runs them throughzod-to-json-schemawithout setting$refStrategyortarget, so it falls back to'root'+jsonSchema7and back-refs every duplicate.Real fix is in the typescript-sdk, they should either expose
$refStrategyor just default tool inputs to'none'. probably worth poking them about it.Anyway,
--discoveryis still the move for now, confirmed zero $refs there.daveCode-dot commentedon May 15, 2026
@eirikb thanks for the deep dive — that's the real root cause, not the surface "refs are malformed" interpretation I went on first.
I checked
modelcontextprotocol/typescript-sdkand there's no open or closed issue about exposing$refStrategy/ changing thezod-to-json-schemadefault for tool inputs. That's a clean gap. Happy to open one upstream citing your analysis (64/311 tools, 1190 back-refs, root strategy fallback, kimi rejection) unless you prefer to file it yourself — your repro is concrete enough to act on directly.Worth noting:
remove-recursive-refs.jsalready in this repo explicitly disclaims it won't help "if the tool still struggles with $ref in general" — which is exactly the kimi case. So kimi falls outside what that helper is scoped to fix.For now
--discoveryis the move (confirmed). Long term, the typescript-sdk patch is the right place. Ping me if you want me to draft the upstream issue.eirikb commentedon May 15, 2026
@daveCode-dot If you want to create an upstream issue that would be great, thanks 👍
daveCode-dot commentedon May 15, 2026
@eirikb done — filed upstream as modelcontextprotocol/typescript-sdk#2100.
Quick recap of what's in the issue, sourced from your dump + a look at the SDK source:
packages/core/src/util/standardSchema.ts:200, wherez.toJSONSchemais called withoutreused. That's the knob that controls whether duplicates get$ref'd or inlined.reused: 'inline'. That matches what--discoverymode already produces in practice (no refs).Offered to put up the PR with a regression test that asserts no
$refin the output of a tool with reused inner schemas. Will wait for upstream direction before pushing code.Thanks for the dump — having
64/311 · 1190 refsin hand made the issue concrete instead of speculative.eirikb commentedon Jul 21, 2026
Fixed by #576 :)