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
-
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", ...})
-
Call the tool passing objects to both parameters
-
Expected: Both parameters received as objects
-
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
These were marked closed but the bug persists in v2.1.7, possibly because the root cause ($ref handling) wasn't identified.
Environment
Description
When calling MCP tools, parameters whose schema uses
$refare incorrectly serialized as JSON strings instead of objects. Parameters with directtype: objectschemas in the same tool call are handled correctly.Reproduction
Use an MCP server with a tool that has both:
$ref(e.g.,"parent": {"$ref": "#/$defs/parentRequest"})"properties": {"type": "object", ...})Call the tool passing objects to both parameters
Expected: Both parameters received as objects
Actual: The
$refparameter is received as a stringified JSON stringEvidence
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:
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
$defssection containsparentRequestdefined as aoneOfunion, but the issue appears to be triggered by the$refitself, not theoneOf.Impact
This breaks any MCP tool that uses
$reffor parameter schemas, including:Related Issues
These were marked closed but the bug persists in v2.1.7, possibly because the root cause (
$refhandling) wasn't identified.