[BUG] MCP tool parameters using $ref enum types are serialized as null

[somanshreddy]

Title: [BUG] MCP tool parameters using $ref enum types are serialized as null

---

Preflight Checklist

• I have searched for existing issues
• This is a single bug report (not multiple issues)
• I am on the latest version of Claude Code

What's Wrong?

When an MCP tool parameter's JSON Schema uses a $ref pointer to an enum definition in $defs, Claude serializes the parameter value as null regardless of what the model intends to send. The model correctly identifies the value to send (visible in its reasoning), but the serialized tool call payload contains null.

Inline enum values (without $ref) work correctly.

What Should Happen?

Claude should resolve $ref pointers in $defs and serialize the intended enum value. Both schema shapes represent the same constraint and should produce the same behavior.

Steps to Reproduce

1. Create an MCP server with two tools. One uses an inline enum, the other uses a $ref enum:

from fastmcp import FastMCP
from enum import Enum
from typing import Optional, Literal
from pydantic import Field

mcp = FastMCP("test-server")

class Priority(str, Enum):
    HIGH = "high"
    MEDIUM = "medium"
    LOW = "low"

# Tool A: inline Literal enum (WORKS)
@mcp.tool()
def create_task_inline(
    title: str = Field(description="Task title"),
    priority: Optional[Literal["high", "medium", "low"]] = Field(
        default=None, description="Task priority"
    ),
) -> str:
    return f"Created task: title={title}, priority={priority}"

# Tool B: $ref enum via Pydantic class (BROKEN)
@mcp.tool()
def create_task_ref(
    title: str = Field(description="Task title"),
    priority: Optional[Priority] = Field(
        default=None, description="Task priority"
    ),
) -> str:
    return f"Created task: title={title}, priority={priority}"

2. The two tools produce different JSON Schema shapes:

Tool A (inline, works):

{
  "priority": {
    "anyOf": [
      {"enum": ["high", "medium", "low"], "type": "string"},
      {"type": "null"}
    ],
    "default": null
  }
}

Tool B ($ref, broken):

{
  "$defs": {
    "Priority": {"enum": ["high", "medium", "low"], "type": "string"}
  },
  "priority": {
    "anyOf": [
      {"$ref": "#/$defs/Priority"},
      {"type": "null"}
    ],
    "default": null
  }
}

3. Ask Claude to call both tools with priority="high".

4. Tool A receives priority="high". Tool B receives priority=null.

Additional patterns tested

The bug also affects non-nullable $ref enums with defaults:

{
  "$defs": {
    "OutputFormat": {"enum": ["mp4", "webm"], "type": "string"}
  },
  "output_format": {
    "$ref": "#/$defs/OutputFormat",
    "default": "mp4"
  }
}

When the model sets output_format="webm", the server receives null. Depending on server validation/normalization, this either fails validation or is treated as omitted and falls back to the default "mp4".

Test matrix

Parameter type	Schema shape	Value sent	Value received
Optional[Literal["high", "medium", "low"]]	inline enum	"high"	"high"
Optional[Priority] (str Enum class)	$ref to $defs	"high"	null
str	{"type": "string"}	"test"	"test"
Optional[str]	anyOf[string, null]	"test"	"test"
bool	{"type": "boolean"}	true	true
int	{"type": "integer"}	3	3

Only $ref enum parameters are affected. All primitive types and inline enums work.

Error Messages/Logs

No error is raised. The value is silently sent as null, making the bug difficult to detect. If the server has null-stripping logic or default fallbacks, the user gets wrong output with no indication of failure.

Is this a regression?

Unknown

Claude Code Version

1.0.33

Platform

Anthropic API

Operating System

Linux

Terminal/Shell

zsh

Additional Information

• Reproducible on both Claude Code (CLI) and Claude.ai (web) with connected MCP servers.
• The Pydantic $ref pattern is standard JSON Schema. MCP servers using Pydantic v2 str, Enum types may hit this when their tool schema exposes those enums through $ref definitions.
• Python's fastmcp framework (used by many MCP servers) produces $ref schemas by default for enum types.
• Related Cursor forum report with the same root cause: https://forum.cursor.com/t/mcp-server-cant-handle-enums-from-my-python-fastmcp-server/99092
• Related MCP Inspector issue: FastMCP parameters not serializing to tool parameters (always null) modelcontextprotocol/inspector#672
• Server-side workaround: replace $ref enum types with inline Literal[...] in tool signatures at codegen time. This produces the working schema shape without changing runtime behavior.

[github-actions]

Found 1 possible duplicate issue:

1. [BUG] MCP tool parameters with $ref schemas are incorrectly serialized as strings #18260

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[somanshreddy]

Likely related to #18260, which reports $ref parameters for object types being serialized as stringified JSON. Both issues stem from the MCP client not resolving $ref pointers in tool parameter schemas. The symptom differs by referenced type: objects get stringified, enums get sent as null.

[somanshreddy]

Server-side workaround for Python/Pydantic MCP servers

If your MCP server uses FastMCP with Pydantic v2 str, Enum types, replace enum class type hints with inline Literal[...] in your tool signatures:

# Before (produces $ref schema, broken)
class Priority(str, Enum):
    HIGH = "high"
    MEDIUM = "medium"
    LOW = "low"

@mcp.tool()
def create_task(priority: Optional[Priority] = None): ...

# After (produces inline enum schema, works)
@mcp.tool()
def create_task(priority: Optional[Literal["high", "medium", "low"]] = None): ...

Pydantic v2 automatically coerces the incoming string to the enum member if your internal models still use the enum class, so no runtime behavior changes.

For context, a fix at the MCP SDK level is also in progress: modelcontextprotocol/typescript-sdk#1563 adds $ref inlining in schemaToJson() for Zod-based servers. Non-Zod servers (Python, Rust, etc.) would still benefit from either a client-side fix or the workaround above.

[PengSpirit]

The test matrix is sharp — the asymmetry between inline Literal and $ref is the key finding here. Two adjacent observations from running into the same path with Pydantic-generated schemas:

The bug isn't just enum-specific — it's a $ref resolution gap. Any $ref pointer into $defs (or definitions) on a parameter is at risk, not only enums. Try the same shape with Optional[CustomModel] where CustomModel is a simple Pydantic class with two string fields; the model can name the field correctly in its reasoning but the serialized payload arrives as null or as a flat dict missing the inner structure. Enums make the bug visually obvious because the value space is finite and the wrong value is a hard fail. Non-enum $refs lose information more silently.

Server-side workaround that doesn't require codegen changes: if you're on FastMCP, you can post-process the tool's inputSchema in your @mcp.tool() decorator wrapper to inline $refs before the server returns tools/list. FastMCP exposes the schema dict on the tool object; resolving $defs once at startup is ~15 lines of jsonschema.RefResolver and avoids changing every Optional[Enum] to Optional[Literal[...]] by hand.

The Cursor forum link in the OP and the Inspector issue both confirm this is a client-side resolver gap, not a server bug. Worth filing the same issue against @modelcontextprotocol/typescript-sdk since that's where most third-party clients pull their schema handling — if the SDK ships a resolver, every client downstream benefits.

For catching this at CI time before it hits an agent (which is what burned me on this — silent null deliveries that pass server-side null-coalescing and produce wrong output with no error), npx @incultnitostudiosllc/mcp-probe test "<launch command>" flags parameters where the resolved schema and the on-wire schema disagree. Complements MCP Inspector's interactive view — Inspector for "is the schema what I think it is", probe-style scan for "do all my tools survive $ref resolution".

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.