[BUG] MCP tool parameters with $ref schemas are incorrectly serialized as strings

Environment

• Claude Code version: 2.1.7
• OS: macOS (Darwin 24.6.0)
• MCP Server: @notionhq/notion-mcp-server v2.0.0

Description

When calling MCP tools, parameters whose schema uses $ref are incorrectly serialized as JSON strings instead of objects. Parameters with direct type: object schemas in the same tool call are handled correctly.

Reproduction

1. Use an MCP server with a tool that has both:

• A parameter using $ref (e.g., "parent": {"$ref": "#/$defs/parentRequest"})
• A parameter with direct object schema (e.g., "properties": {"type": "object", ...})

1. Call the tool passing objects to both parameters

1. Expected: Both parameters received as objects
2. Actual: The $ref parameter is received as a stringified JSON string

Evidence

I created a wrapper around the Notion MCP server to intercept traffic. When calling API-post-page:

What Claude Code sent:

{
  "parent": "{\"data_source_id\": \"2e85ff8b-a448-8010-a867-000bc4ae78d2\"}",
  "properties": {
    "Phone Model": {
      "title": [{"text": {"content": "DEBUG TEST"}}]
    }
  }
}

Analysis:
| Parameter | Schema | Type Received |
|-----------|--------|---------------|
| parent | {"$ref": "#/$defs/parentRequest"} | string (wrong) |
| properties | {"type": "object", "properties": {...}} | object (correct) |

Both parameters were passed identically in my tool call, but only parent (with $ref) was stringified.

Schema Details

From the MCP server's tool definition:

{
  "properties": {
    "parent": {"$ref": "#/$defs/parentRequest"},
    "properties": {
      "type": "object",
      "properties": {
        "title": {...}
      },
      "required": ["title"],
      "additionalProperties": false
    }
  }
}

The $defs section contains parentRequest defined as a oneOf union, but the issue appears to be triggered by the $ref itself, not the oneOf.

Impact

This breaks any MCP tool that uses $ref for parameter schemas, including:

• Notion MCP server (official @notionhq/notion-mcp-server)
• Any server using JSON Schema references for complex types

Related Issues

• #3084 - FastMCP Pydantic model parameters (closed)
• #5504 - JSON objects serialized as strings (closed as dup of #3084)
• #3023 - Notion-MCP parent double-stringified (closed)

These were marked closed but the bug persists in v2.1.7, possibly because the root cause ($ref handling) wasn't identified.