codex - 💡(How to fix) Fix Clarify/support plugin-root relative paths in plugin-provided .mcp.json

Summary

I may be misunderstanding the intended plugin behavior, but I expected a plugin-provided .mcp.json to have a documented way to reference files bundled inside the same plugin.

Currently, relative paths inside MCP args appear to resolve from the Codex process/workspace cwd rather than the plugin root. This makes bundled MCP servers difficult to distribute without hard-coded absolute paths.

Environment

• Codex CLI: codex-cli 0.130.0
• OS: Windows
• Plugin source: local marketplace plugin
• Installed plugin cache path shape: C:\Users\<user>\.codex\plugins\cache\<marketplace>\<plugin>\<version>\
• MCP server command uses uv

Plugin structure

The plugin is installed into Codex's plugin cache and contains a bundled MCP server directory next to .mcp.json:

<plugin-root>/
  .codex-plugin/plugin.json
  .mcp.json
  bundled-mcp-server/
    server.py
    pyproject.toml

The plugin manifest points to .mcp.json relative to the plugin root:

{
  "name": "example-plugin",
  "version": "1.0.0",
  "mcpServers": "./.mcp.json"
}

The .mcp.json uses a relative path intended to refer to the bundled MCP server directory:

{
  "mcpServers": {
    "example-server": {
      "command": "uv",
      "args": ["run", "--no-sync", "--directory", "./bundled-mcp-server", "server.py"]
    }
  }
}

Actual behavior

codex mcp list showed the plugin MCP server registered, but with empty Cwd:

Name            Command  Args                                                        Cwd
example-server  uv       run --no-sync --directory ./bundled-mcp-server server.py     -

When Codex was started from C:\Users\<user>, the relative ./bundled-mcp-server path effectively resolved from that working directory instead of the plugin root, and startup failed with:

error: The system cannot find the file specified. (os error 2)

Running the same server with --directory set to the absolute plugin cache path worked.

Expected / requested behavior

If plugin-packaged MCP servers are intended to be supported, there should be a documented way to reference paths relative to the installed plugin root. For example, any of these would solve the portability issue:

• launch plugin-provided MCP servers with cwd set to the plugin root
• support a cwd field in plugin .mcp.json that can be resolved relative to the plugin root
• support a variable such as ${PLUGIN_DIR} / ${CODEX_PLUGIN_ROOT} inside plugin MCP configs
• document that .mcp.json paths are not plugin-root-relative and recommend a portable wrapper pattern

Why this matters

Hard-coding paths such as:

C:\Users\<user>\.codex\plugins\cache\...

works locally, but breaks plugin portability across users, machines, and cache locations. Relative paths are the natural format for packaged plugins that include their own MCP server implementation.

Related issues

This seems related to previous MCP cwd / relative path reports, but specifically for plugin-provided .mcp.json files:

• #14573
• #16390
• #4222
• #19372

Workaround

Disable the plugin or manually configure the MCP server with an absolute path in config.toml. That workaround is not suitable for distributing plugins.