mcp-server: `model` parameter schema documents stale example ids (gpt-5.2), misleading MCP clients into pinning an old model

Summary

The model parameter of the codex tool exposed by codex mcp-server documents gpt-5.2 / gpt-5.2-codex as its examples. Those ids are several releases stale, and the doc comment is still on main.

codex-rs/mcp-server/src/codex_tool_config.rs:

/// Optional override for the model name (e.g. 'gpt-5.2', 'gpt-5.2-codex').

Why this is worth fixing rather than cosmetic

For an MCP client, that string is not decoration — it is the only concrete model id anywhere in the tool contract. An LLM-driven client reading the schema to learn how to call the tool sees gpt-5.2 presented as the exemplar and can reasonably pass it, silently pinning a session to an old model. The parameter is a free-form string with no enum and no validation, so nothing rejects the stale value; the downgrade is invisible until someone inspects the session rollout.

This is not hypothetical. Driving the tool from two MCP client agents, one of them stopped and asked whether gpt-5.2 was the model it was supposed to use, because the schema was the only model information available to it. The same binary's own model registry lists the current family, so the doc comment is the sole stale surface.

Reproduce

$ codex --version
codex-cli 0.148.0

$ strings "$(npm root -g)/@openai/codex/node_modules/@openai/codex-darwin-arm64/vendor/aarch64-apple-darwin/bin/codex" \
    | grep -oE "Optional override for the model name \(e\.g\.[^)]*\)\."
Optional override for the model name (e.g. 'gpt-5.2', 'gpt-5.2-codex').

Or start codex mcp-server and read the model property description in the codex tool's tools/list schema.

Confirmed present on main as of this writing, so 0.150.0 does not fix it.

Suggested fix

Either refresh the examples to current ids, or — since any literal id will drift again the same way — drop the examples and describe the fallback behaviour instead, which is stable:

/// Optional override for the model name. When omitted, the model is resolved
/// from CODEX_HOME/config.toml.

The second form is self-maintaining and, for an MCP client, more actionable than any example: what a client most needs to know is that omitting the field is the correct default.

Environment

• codex-cli 0.148.0, macOS (darwin-arm64), installed via npm
• Also verified against codex-rs/mcp-server/src/codex_tool_config.rs on main