Docs: plugin .mcp.json example uses mcp_servers but Codex expects mcpServers

[heliusjing]

Affected documentation URL

https://developers.openai.com/codex/plugins/build#bundled-mcp-servers-and-lifecycle-config

Problem

The plugin documentation says that mcpServers in .codex-plugin/plugin.json can point to an .mcp.json file, and then shows this wrapped .mcp.json format:

{
  "mcp_servers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

In practice, this wrapped format is not recognized by Codex for plugin MCP config in my testing. Changing the wrapper key to mcpServers makes the MCP server load correctly:

{
  "mcpServers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

A direct top-level server map also works:

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

Evidence from current code

The current plugin MCP parser appears to deserialize the wrapped plugin MCP file with camelCase JSON field names:

• codex-rs/core-plugins/src/loader.rs
  • PluginMcpServersFile has #[serde(rename_all = "camelCase")]
  • the Rust field is named mcp_servers, which maps to JSON mcpServers, not JSON mcp_servers
• codex-rs/core-plugins/src/loader_tests.rs
  • plugin_mcp_file_supports_mcp_servers_object_format parses JSON containing "mcpServers"
  • the flat map test parses a direct top-level server map

This also matches the rust-v0.123.0 release note for PR #18780, which says plugin MCP loading supports .mcp.json files containing an mcpServers object or top-level server maps:

#18780

Local version where reproduced

codex-cli 0.130.0

Suggested docs change

In the "Bundled MCP servers and lifecycle config" section, change the wrapped server map example from mcp_servers to mcpServers, or clarify that plugin .mcp.json accepts mcpServers and direct top-level server maps, while mcp_servers is the TOML/config naming used in ~/.codex/config.toml.

The corrected plugin .mcp.json wrapper example would be:

{
  "mcpServers": {
    "docs": {
      "command": "docs-mcp",
      "args": ["--stdio"]
    }
  }
}

Notes

I tried to locate the source for the developers.openai.com Codex plugin docs in this public repository but could not find the page source via GitHub code search or the repo tree, so I am filing this as a docs issue instead of opening a documentation PR.