HTTP MCP server: "tools fetch failed" on tools/list with large $ref/$defs schemas (Google Stitch)

Summary

An HTTP MCP server that connects successfully and advertises tools fails at the tools/list step with "Connected · tools fetch failed", so none of its tools load. The root cause appears to be the size / $ref+$defs structure of the server's tools/list response — the same request succeeds outside Claude Code.

Environment

• Claude Code: 2.1.195
• Node: v26.3.0
• Platform: macOS (darwin 25.5.0)
• Server: Google Stitch MCP (https://stitch.googleapis.com/mcp), transport http, header-based auth (X-Goog-Api-Key)

Repro

claude mcp add stitch https://stitch.googleapis.com/mcp \
  --transport http --header "X-Goog-Api-Key: <REDACTED>"
claude mcp list
# stitch: https://stitch.googleapis.com/mcp (HTTP) - ! Connected · tools fetch failed

Evidence the server/key/request are fine

Replaying Claude Code's exact request headers with curl (User-Agent: claude-code/2.1.195 (sdk-cli), Accept: application/json, text/event-stream, Accept-Encoding: identity, mcp-protocol-version: 2025-06-18):

• initialize → HTTP 200
• tools/list → HTTP 200, 14 tools, ~340KB body, 0.8s

The server is stateless and returns no Mcp-Session-Id (none required). So auth, connectivity, and the request shape are all correct.

Evidence the failure is client-side

Claude Code's own MCP transport log:

Successfully connected (transport: http) in 664ms
Connection established with capabilities: {"hasTools":true, ... "serverVersion":{"name":"StatelessServer",...}}

Handshake + initialize succeed and hasTools:true. The subsequent tools/list is where it fails. The transport debug log does not record the tools/list error itself — only "tools fetch failed" surfaces in claude mcp list.

Likely cause

The tools/list response is ~340KB. All 14 tools carry outputSchema values built from $ref/$defs, several ~36KB each (generate_screen_from_text, edit_screens, generate_variants, apply_design_system). inputSchema values range 170B–14KB. Registration appears to fail on the size and/or $ref/$defs output-schema structure rather than on any transport/auth problem.

Expected

Tools with large or $ref/$defs-based schemas (especially outputSchema) should register successfully, or claude mcp list should surface the actual underlying error instead of a generic "tools fetch failed".

Suggestions

1. Log the concrete tools/list failure (parse error, size cap, schema-validation error) in the MCP transport debug log.
2. If there is a response-size or schema-complexity cap, document it and/or raise it.
3. Tolerate $ref/$defs in outputSchema during tool registration.