MCP HTTP client fails to resolve JSON Schema $ref (#/$defs/ScreenInstance) from Google Stitch MCP server

Open 💬 0 comments Opened Jul 9, 2026 by Lauraffcosta

Claude Code version: 2.1.205 (macOS, Darwin 25.5.0)

Steps to reproduce:

  1. claude mcp add stitch --transport http https://stitch.googleapis.com/mcp --header "X-Goog-Api-Key: <valid key>" -s user
  2. claude mcp list or claude 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.

View original on GitHub ↗