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?
- Set up an MCP server with FastMCP/Pydantic models that generate JSON schemas with
$ref references
- Configure Codex CLI to connect to the MCP server
- Run
codex and list available tools
- 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:
- Missing
$defs field: The ToolInputSchema struct doesn't include a $defs field to capture schema definitions
- No
$ref resolution: The schema sanitization function doesn't resolve $ref references
- 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:
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?
$refreferencescodexand list available tools{"request": string}instead of the full parameter structureExample 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:
What do you see instead?
Tool parameters are displayed as a simple string type, losing all parameter details:
Additional information
Root Cause Analysis:
The issue occurs in the JSON Schema processing pipeline in the MCP tool conversion code:
$defsfield: TheToolInputSchemastruct doesn't include a$defsfield to capture schema definitions$refresolution: The schema sanitization function doesn't resolve$refreferences$refare converted to the internalJsonSchemaenum, the referenced definitions are lostImpact:
Verification:
$refreferencesRelated Issues:
$refresolution, not basic type conversion