Plugin MCP server keys with hyphens are listed but not exposed as callable tools #33063

Summary

A plugin-provided MCP server whose .mcp.json key contains a hyphen can appear enabled in codex mcp list, but its tools are not exposed to the model as callable mcp__... tools. Renaming the MCP server key from context-library to context_library made the same server immediately callable.

This is easy to confuse with MCP startup or tools/list failures, because the plugin skill is loaded and codex mcp get <server> shows the server configuration, but the model cannot call or discover the tools.

Environment

• Codex CLI: codex-cli 0.144.3
• Platform: Linux x86_64 / RHEL-family host
• Plugin source: local marketplace plugin
• Plugin shape:
  • .codex-plugin/plugin.json with "mcpServers": "./.mcp.json"
  • bundled stdio Python MCP server
  • plugin skill loaded successfully

Reproduction

Install a local plugin whose .mcp.json uses a hyphenated MCP server key:

{
  "mcpServers": {
    "context-library": {
      "command": "python3",
      "args": ["./mcp/context_library_server.py"],
      "cwd": "./"
    }
  }
}

After installing the plugin:

codex plugin add context-library@vcinity-eng
codex mcp get context-library

codex mcp get reports the server as enabled. However, a fresh codex exec cannot call or discover the expected tool namespace:

mcp__context-library__get_library_status

The model reports that the MCP tool is not available / not exposed.

Now change only the MCP server key from context-library to context_library:

{
  "mcpServers": {
    "context_library": {
      "command": "python3",
      "args": ["./mcp/context_library_server.py"],
      "cwd": "./"
    }
  }
}

Reinstall the plugin, then run a fresh codex exec asking it to call:

mcp__context_library__get_library_status

The same MCP server becomes callable and returns a valid result.

Actual behavior

• Hyphenated MCP server key is accepted/listed by codex mcp list / codex mcp get.
• Plugin skill loads successfully.
• The tool namespace is not exposed to the model as callable tools.
• There is no clear diagnostic explaining that the MCP server key is invalid or unsupported for model-visible tool naming.

Expected behavior

One of these should happen:

1. Codex rejects plugin MCP server keys that cannot become valid callable model tool namespaces, with a clear validation error at install/load time.
2. Codex normalizes hyphenated MCP server keys into a valid namespace, such as context_library.
3. Codex documents that plugin-provided MCP server keys must be valid callable namespace identifiers and surfaces a diagnostic when tools are dropped for naming reasons.

Related issue found while debugging

This was discovered alongside plugin-root path handling problems. That separate concern is already covered by:

• Clarify/support plugin-root relative paths in plugin-provided .mcp.json #22842
• Codex CLI does not interpolate ${CLAUDE_PLUGIN_ROOT} in plugin .mcp.json args, breaking imessage MCP #19582

For this issue, after changing the launch config to use cwd: "./" and a relative args path, the remaining difference was the MCP server key: hyphenated key not callable, underscore key callable.

Impact

Plugin authors can ship an MCP server that appears installed and enabled, but agents cannot use its tools. The failure mode sends users toward debugging MCP transport/server implementation even though the practical fix is just the server key name.