MCP HTTP client fails to resolve JSON Schema $ref (#/$defs/ScreenInstance) from Google Stitch MCP server
Claude Code version: 2.1.205 (macOS, Darwin 25.5.0)
Steps to reproduce:
claude mcp add stitch --transport http https://stitch.googleapis.com/mcp --header "X-Goog-Api-Key: <valid key>" -s userclaude mcp listorclaude mcp get stitch
Expected: Server connects and tools load successfully.
Actual:
stitch: https://stitch.googleapis.com/mcp (HTTP) - ! Connected . tools fetch failed
Issue: can't resolve reference #/$defs/ScreenInstance from id #Verification the server itself is fine:
A raw curl POST to the same endpoint with the same API key, calling tools/list directly over the MCP JSON-RPC protocol, returns a valid response including a create_project tool whose outputSchema contains nested $defs and $ref entries (e.g. referencing ScreenInstance). The raw JSON-RPC response is well-formed.
This suggests Claude Code's MCP client has a bug resolving $ref pointers into $defs when the referenced schema is nested inside a tool's outputSchema (as opposed to top-level inputSchema), causing the entire tools/list fetch to fail rather than degrading gracefully or skipping the one problematic tool.
Impact: The Stitch MCP server (stitch.googleapis.com/mcp) cannot be used at all from Claude Code, even with a correct, working API key.
3 Comments
Still reproduces on Claude Code 2.1.218 (VS Code ext, Windows 11) — currently the latest published release (npm dist-tags → latest: 2.1.218), so no update resolves it. claude mcp get stitch → ! Connected · tools fetch failed / can't resolve reference #/$defs/ScreenInstance from id #. Deterministic across restarts. Root cause in #77106 (recursive $ref in Stitch's ScreenInstance, no cycle detection). Server remains unusable from Claude Code on latest.
+1
Reproduced on 2.1.233 (Linux) — confirmed, though the root trigger is slightly different from the description.
A well-formed
outputSchemawith$refpointing into$defsactually resolves fine (tested as a control — the server connects and tools load). The real trigger: the Stitch server'supload_design_mdtool declares"$ref": "#/$defs/ScreenInstance"in itsoutputSchemabut that schema contains no$defsat all — a dangling reference (you can see it in your rawtools/listcurl output). The schema validator correctly rejects it.The bug on our side: one tool with an unresolvable schema fails the entire tools fetch, so the server's 15 other perfectly valid tools don't load either. We should skip the malformed tool and load the rest — keeping this open to track that fix.
In the meantime, this is also worth reporting to the Stitch team: their
upload_design_mdoutput schema references#/$defs/ScreenInstancewithout defining it, which will trip up spec-compliant MCP clients generally.🤖 Generated with Claude Code