MCP tools/list emits unresolvable $ref in outputSchema (upload_design_md dangling, ScreenInstance recursive) — clients drop all tools

[Roelsoft]

Summary

Four tools returned by tools/list at https://stitch.googleapis.com/mcp carry an outputSchema with a $ref that MCP clients cannot dereference. One is a dangling reference; three are self-recursive. Clients that eagerly resolve $ref when registering tools reject the entire tool list, so the server connects successfully and then exposes zero tools.

Filing here as the public repo for Stitch's API surface — the defect is in the schemas the hosted MCP server emits, not in the SDK code itself.

Affected tools

Captured from a live tools/list (15 tools total):

1. upload_design_md — dangling reference

Its outputSchema is the ScreenInstance object inlined at the root, but it retains a self-reference with no $defs block present to resolve it:

outputSchema.$defs                                          → absent
outputSchema./properties/variantScreenInstance/$ref          → "#/$defs/ScreenInstance"

2. create_project, get_project, list_projects — recursive reference

Here ScreenInstance is defined under $defs, but it refers to itself:

outputSchema./$defs/ScreenInstance/properties/variantScreenInstance/$ref → "#/$defs/ScreenInstance"

list_projects additionally reaches it via /$defs/Project/properties/screenInstances/items.

The remaining 11 tools have schemas that resolve cleanly.

Impact

In Claude Code the server reports:

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

Authentication and tool calls work fine — the failure is purely schema registration — but because a single unloadable schema aborts the whole fetch, all 15 tools become unavailable and the integration is unusable as documented.

Corresponding client-side reports: anthropics/claude-code#76040 and anthropics/claude-code#81111 (both open, reproducing on current releases).

Reproduction

curl -s -X POST https://stitch.googleapis.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Goog-Api-Key: $STITCH_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
| python3 -c '
import json,sys
def refs(n,a=[]):
    if isinstance(n,dict):
        if isinstance(n.get("$ref"),str): a.append(n["$ref"])
        for v in n.values(): refs(v,a)
    elif isinstance(n,list):
        for v in n: refs(v,a)
    return a
def resolve(root,ref):
    cur=root
    for p in ref[2:].split("/"):
        if isinstance(cur,dict) and p in cur: cur=cur[p]
        else: return None
    return cur
for t in json.load(sys.stdin)["result"]["tools"]:
    s=t.get("outputSchema")
    if not s: continue
    bad=[r for r in refs(s,[]) if resolve(s,r) is None]
    rec=[r for r in refs(s,[]) if r.endswith("ScreenInstance")
         and resolve(s,r) is not None and r in refs(resolve(s,r),[])]
    if bad or rec: print(t["name"], "dangling:", set(bad), "recursive:", set(rec))
'

Suggested fix

1. For upload_design_md, emit the $defs block alongside the inlined root schema (or drop the variantScreenInstance property from that response schema if it is not actually returned).
2. For the recursive ScreenInstance, the cleanest option is to break the cycle in the generated schema — omit variantScreenInstance, or bound it to one level of nesting — since a self-referential $defs entry is legal JSON Schema but not universally consumable by MCP clients.

Clients arguably should tolerate a recursive $ref, and that is being tracked separately upstream. The dangling reference in upload_design_md is unambiguously a server-side bug either way.

Workaround

For anyone blocked today: put a stdio shim in front of the endpoint that forwards everything untouched and strips any outputSchema containing an unresolvable or cyclic $ref. outputSchema is optional and advisory in MCP, so all 15 tools stay callable and results are unaffected.

[percymcn]

Two things that bear on how this gets fixed, both measured today against the shapes described above (I have no Stitch API key, so this is the shape your report documents, not a capture from your live endpoint).

1. The dangling case and the recursive cases are not the same defect, and only one of them is server-side.

A $ref to a $defs entry that exists and refers to itself is legal JSON Schema. I built both shapes and fed them to the three constrained decoders that back most structured-output stacks:

shape	xgrammar 0.2.5	outlines-core 0.2.14	lm-format-enforcer 0.11.3
recursive, $defs present	builds	builds	builds
dangling, $defs absent	RuntimeError: Cannot find field ScreenInstance	ValueError: Invalid reference path: $defs	ValueError: No definitions found in schema

So create_project / get_project / list_projects are fine as emitted — every consumer I can test resolves them. The eager-resolver failure you're seeing on those is a client-side conformance gap (which is what your two linked claude-code issues are about), not something the server should work around. upload_design_md is the one genuine schema defect here.

That matters for scoping: if the change is "stop emitting self-references," it fixes nothing that was broken and makes three currently-correct schemas worse.

2. upload_design_md cannot be fixed by inlining — the only correct fix is to emit the $defs block.

Inlining the one dangling reference is the obvious minimal repair, and it can't terminate here: by your own data the dangling ref points at ScreenInstance, and ScreenInstance is self-recursive (that's exactly what tools 2–4 show). Expanding it in place doesn't have a fixed point. Whatever is currently inlining ScreenInstance at the root of that schema is presumably what dropped the bag, so the fix is to keep $defs alongside it rather than to inline harder.

3. Worth knowing before you triage severity: this fails loudly in some consumers and silently in others.

anthropic==0.121.0's transform_schema accepts a dangling #/$defs/X and forwards it verbatim — no error, no warning, the request goes out and the referenced constraint is simply absent. So downstream of a client that doesn't eagerly resolve, this doesn't surface as a tools-fetch failure; it surfaces as a field that quietly stopped being constrained. The loud failure you're hitting in Claude Code is the better of the two outcomes.

One test-design note. A regression check of the form "every $ref in every outputSchema resolves" is the right assertion, but it passes on create_project either way — the discriminating fixture is upload_design_md specifically, and a resolver written to also descend into what it resolved will not terminate on the recursive three unless it tracks visited pointers. That's a plausible reason a check like this isn't already in CI.

[bensynapse]

Confirming from a third MCP client — kimi-code 0.38.0 (current release) refuses to register the server for the same reason:

ERROR mcp server unavailable  server=stitch transport=http status=failed reason="can't resolve reference #/$defs/ScreenInstance from id #"

Reproduced today (2026-08-21) against the live endpoint: upload_design_md's outputSchema still references #/$defs/ScreenInstance with no $defs block present, and it is still the only one of the 15 tools whose schema fails to resolve. initialize and direct tools/call (e.g. list_projects) work fine when the schema-registration step is bypassed — consistent with @percymcn's analysis above that upload_design_md is the genuine server-side defect, while the recursive-but-defined cases are client conformance gaps.

Workaround that unblocks strict clients until the schema is fixed: put a small local stdio MCP proxy in front of https://stitch.googleapis.com/mcp that rewrites the tools/list response — collect every $defs map found in the response and merge it into each input/output schema, so all local #/$defs/... refs resolve. (Same idea as #353/#355, just at the client boundary instead of inside the SDK.) With the patched tool list, kimi-code connects and all 15 tools work.

Happy to share the captured tools/list JSON or the proxy script if useful.