MCP Parser Fails on JSON Schema $ref References (Google Stitch)

[jdinix]

Bug Report: MCP Parser Fails on JSON Schema $ref References (Google Stitch)

Description

MiMoCode's MCP client fails to load tools from remote MCP servers that use complex JSON Schema $ref and $defs references in their tool input schemas.

Affected MCP Server

Google Stitch - https://stitch.googleapis.com/mcp

Google Stitch is Google's AI design tool that provides an MCP server for programmatic access.

Error

ERROR service=mcp key=Google Stitch error=can't resolve reference #/$defs/ScreenInstance from id # failed to get tools from client

Steps to Reproduce

1. Add Google Stitch MCP to config:

{
  "mcp": {
    "Google Stitch": {
      "type": "remote",
      "url": "https://stitch.googleapis.com/mcp"
    }
  }
}

2. Run mimo mcp list
3. Observe the "Failed to get tools" error

Expected Behavior

MiMoCode should parse JSON Schema $ref and $defs references and resolve them correctly, allowing MCP servers with complex schemas to work.

Actual Behavior

The parser fails with can't resolve reference #/$defs/ScreenInstance from id #.

Server Verification

The server responds correctly to raw HTTP requests:

curl -X POST https://stitch.googleapis.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Returns 14 tools including create_project, generate_screen_from_text, edit_screens, etc.

Environment

• MiMoCode version: 0.1.5
• OS: Linux

Additional Context

This affects any MCP server that uses JSON Schema $ref for complex type definitions. The Google Stitch schemas are particularly complex with nested references like:

• #/$defs/ScreenInstance
• #/$defs/DesignSystem
• #/$defs/Screen

[jdinix]

Update: API Key authentication works, but schema parsing fails

After testing with a valid API key (X-Goog-Api-Key header), the Google Stitch MCP server responds correctly:

curl -X POST https://stitch.googleapis.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: <VALID_KEY>' \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Returns 14 tools successfully: create_project, get_project, list_projects, list_screens, get_screen, generate_screen_from_text, edit_screens, generate_variants, upload_design_md, create_design_system, create_design_system_from_design_md, update_design_system, list_design_systems, apply_design_system.

The real issue: MiMoCode's MCP parser fails with can't resolve reference #//ScreenInstance from id # when trying to parse the tool schemas. The schemas use complex JSON Schema and references that the parser cannot resolve.

Suggested fix: Improve JSON Schema `` resolution in the MCP client to handle nested references like #//ScreenInstance, `#//DesignSystem`, `#//Screen`, etc.

Config that works with API key:

{
  "mcp": {
    "Google Stitch": {
      "type": "remote",
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

[mvalentsev]

Dug into this one — the error comes from the MCP SDK compiling each tool's output schema with ajv right after tools/list. Stitch's upload_design_md has an output property that $refs #/$defs/ScreenInstance but never defines it, so ajv can't resolve the ref and throws, and the whole tool list gets dropped. Fix up at #1733 — it hands the client a tolerant validator so one un-compilable schema doesn't take down the rest of the server's tools.