Stitch MCP (stitch.googleapis.com): tools fetch fails with "can't resolve reference #/$defs/ScreenInstance"

Summary

After successfully authenticating to the Stitch MCP server (https://stitch.googleapis.com/mcp) via API key header, tool discovery fails with a JSON Schema resolution error, making all Stitch tools unavailable.

Environment

• Claude Code CLI: v2.1.220 (also reproduced on VS Code extension v2.1.87 before update, and v2.1.220 after update — not a version regression)
• Platform: macOS
• MCP server: stitch (https://stitch.googleapis.com/mcp, HTTP transport)

Steps to reproduce

1. claude mcp add stitch --transport http https://stitch.googleapis.com/mcp --header "X-Goog-Api-Key: <key>" -s user
2. Run /mcp or call any mcp__stitch__* tool

Observed

claude mcp list shows:

stitch: https://stitch.googleapis.com/mcp (HTTP) - ! Connected · tools fetch failed — can't resolve reference #/$defs/ScreenInstance from id #

Server connects and authenticates successfully, but the entire tool list fails to load because one tool's schema (likely apply_design_system, which references ScreenInstance) contains a $ref that Claude Code's JSON Schema resolver cannot resolve. This takes down all Stitch tools, not just the one with the bad schema.

Root cause (external, not Claude Code's config/auth layer)

This is a malformed/non-standard JSON Schema $defs/$ref structure returned by the Stitch MCP server itself, not an authentication or Claude Code configuration issue. Same error reproduces identically in other MCP clients (OpenCode, Trae, Kilo Code), confirming it's server-side:

• https://github.com/anomalyco/opencode/issues/26260 (fixed client-side in OpenCode via PR #26614 — they patched their schema resolver to tolerate the malformed ref)
• https://github.com/Trae-AI/Trae/issues/2512
• https://github.com/Kilo-Org/kilocode/issues/10041
• https://discuss.ai.google.dev/t/bug-mcp-server-invalid-json-schema-reference-defs-screeninstance/144751 (Google acknowledged, claimed fixed as of 2026-06-08 — but still reproduces as of 2026-07-25, so either a regression or the fix wasn't fully rolled out)

Suggested fix

Since Google's server-side fix is unreliable/incomplete, consider following OpenCode's approach: make Claude Code's JSON Schema resolver tolerant of unresolvable $defs refs on a per-tool basis, so one broken tool schema doesn't block the entire server's toolset from loading.

Related

Separately, note that authenticating via claude mcp add ... --header "X-Goog-Api-Key: ..." (CLI flag) works and gets past auth, whereas configuring headers in a JSON mcp config file reportedly does not (per #41664, closed as not planned) — worth reconciling those two paths.