Workaround Fix for MCP Bug ( returning invalid JSON schema)

Stitch
1

Since this is my first post And I cant use more than one Link so creating a Variable for The Url :

{URL} = https://stitch.googleapis.com

The MCP server at {URL}/mcp returns an invalid JSON Schema
for one tool. Strict MCP clients validate every schema returned by tools/list, so
this single malformed schema makes ALL 15 Stitch tools unusable — not just the
affected one.

Environment

  • Endpoint: {URL}/mcp (HTTP transport, X-Goog-Api-Key auth)
  • serverInfo: {“name”:“StatelessServer”,“version”:“scaffolding on HTTPServer2”}
  • protocolVersion: 2025-06-18
  • Client: Claude Code (MCP)
  • Date observed: 7 Aug 2026

Client-visible error

stitch: {URL}/mcp (HTTP) - Connected ·
tools fetch failed — can’t resolve reference #/$defs/ScreenInstance from id #

Root cause

tools/list returns upload_design_md whose outputSchema is the ScreenInstance
message inlined at the schema root (its description reads “An instance of a screen
on the project. Next ID: 18”).

ScreenInstance is self-referential:

"variantScreenInstance": {
  "$ref": "#/$defs/ScreenInstance",
  "description": "Optional. The variant Screen Instance."
}

Because the message was inlined at the root rather than placed under $defs, no
$defs block was emitted, leaving the self-reference dangling.

Evidence this is a codegen bug, not intended

14 of 15 tools emit $defs correctly. Three tools define ScreenInstance properly:

  • create_project.outputSchema → $defs includes ScreenInstance
  • get_project.outputSchema → $defs includes ScreenInstance
  • list_projects.outputSchema → $defs includes ScreenInstance
    Only upload_design_md omits it. The generator appears to mishandle the case where a
    self-referencing message is used directly as a root output schema.

Reproduction

  1. POST initialize to {URL}/mcp with a valid X-Goog-Api-Key
  2. POST {“jsonrpc”:“2.0”,“id”:2,“method”:“tools/list”,“params”:{}}
  3. Inspect result.tools → find “upload_design_md”
  4. Observe outputSchema contains $ref “#/$defs/ScreenInstance” but has no “$defs” key

Expected

outputSchema should be self-contained, e.g.

{ "$ref": "#/$defs/ScreenInstance",
  "$defs": { "ScreenInstance": { ... } } }

or the inlined root should carry a “$defs” block defining ScreenInstance.

Impact

Any MCP client that validates schemas at tools/list time rejects the entire tool
list. Stitch MCP is currently unusable from such clients.

Workaround

The server itself works fine — calling tools/call directly over JSON-RPC succeeds
(verified with list_projects, create_design_system schema inspection, etc.). Only
the MCP client handshake is blocked.