MCP tool parameters show as string instead of full schema when using JSON Schema $ref references

[ewgdg]

What version of Codex is running?

codex-cli 0.29.0

Which model were you using?

GPT-5

What platform is your computer?

Linux 6.16.4-arch1-1 x86_64 unknown

What steps can reproduce the bug?

1. Set up an MCP server with FastMCP/Pydantic models that generate JSON schemas with $ref references
2. Configure Codex CLI to connect to the MCP server
3. Run codex and list available tools
4. Observe that tools with complex parameter schemas show as simple {"request": string} instead of the full parameter structure

Example MCP server tool schema that triggers the bug:

{
  "type": "object", 
  "properties": {
    "request": {"$ref": "#/$defs/DatabaseQueryRequest"}
  },
  "$defs": {
    "DatabaseQueryRequest": {
      "type": "object",
      "properties": {
        "query": {"type": "string", "description": "SQL query to execute"},
        "limit": {"type": "integer", "default": 100, "description": "Maximum number of results"},
        "format": {"type": "string", "enum": ["json", "csv", "table"], "default": "json"}
      },
      "required": ["query"]
    }
  }
}

What is the expected behavior?

Tool parameters should display the full schema structure, showing all available parameters with their types and descriptions:

example-server__database_query:
- Inputs: 
  - request:
    - query (string, required): SQL query to execute
    - limit (integer, optional): Maximum number of results to return (default: 100)
    - format (string, optional): Output format: json, csv, or table (default: json)

What do you see instead?

Tool parameters are displayed as a simple string type, losing all parameter details:

example-server__database_query:
- Inputs: {"request": string}

Additional information

Root Cause Analysis:
The issue occurs in the JSON Schema processing pipeline in the MCP tool conversion code:

1. Missing $defs field: The ToolInputSchema struct doesn't include a $defs field to capture schema definitions
2. No $ref resolution: The schema sanitization function doesn't resolve $ref references
3. Schema information loss: When MCP schemas with $ref are converted to the internal JsonSchema enum, the referenced definitions are lost

Impact:

• Affects all MCP servers using Pydantic models with complex schemas
• Makes it impossible for users to understand what parameters are available for MCP tools
• Reduces usability of MCP integration significantly

Verification:

• The same MCP server works correctly with other MCP clients that properly resolve $ref references
• Issue confirmed by examining the Codex source code in the MCP tool conversion pipeline

Related Issues:

• Similar to Codex 0.20.0 fails to convert several MCP tools (JSON Schema parsing): integer unsupported, union types rejected, and missing type — Obsidian MCP server #2204 but specifically about $ref resolution, not basic type conversion

[ewgdg]

This is a bug report, can someone add a bug label. Sorry I made a mistake not using the bug report template.
I asked claude to create the gh issue and I did not realize there was a bug report template.