Plugin MCP servers need a supported user secret/env configuration path

Solution: codex #24401 — Plugin MCP servers need a supported user secret/env configuration path

Issue Summary

Plugin MCP servers bundled via .codex-plugin/plugin.json have no standard way to accept user-provided secrets through env_vars. Adding only [mcp_servers.poka.env] in config.toml is treated as a separate incomplete server definition rather than a partial override for the plugin-provided server.

Root Cause Analysis

The MCP server configuration loading has two separate code paths:

1. User-defined servers in config.toml: Full server definition required (command, args, env)
2. Plugin-provided servers from .codex-plugin/plugin.json: Complete definition from plugin bundle

These paths don't support partial deep merge. When a user adds [mcp_servers.poka.env] to override just the env section, Codex treats it as a new incomplete server definition (missing command/args/cwd) rather than merging it with the plugin-provided definition.

The env_vars field is documented for allowing parent environment variables into MCP subprocesses, but there's no documented UX for Desktop users to persistently set those values.

Proposed Fix

Option A: Partial plugin MCP env override (recommended, minimal change)

Allow user config.toml to provide partial overrides that merge with plugin-provided server definitions:

# User adds only env override — merges with plugin's command/args/cwd
[mcp_servers.poka.env]
WORKPLUS_ACCESS_TOKEN = "user-provided-token"

Implementation:

// In MCP config loading (config.ts or similar)
function resolveMcpServerConfig(
  pluginServer: McpServerConfig,  // from plugin.json
  userOverride: Partial<McpServerConfig> | undefined  // from config.toml
): McpServerConfig {
  if (!userOverride) return pluginServer
  
  return {
    // Plugin provides the base config
    command: pluginServer.command,
    args: pluginServer.args,
    cwd: pluginServer.cwd,
    url: pluginServer.url,
    
    // Deep merge env: user overrides take precedence
    env: {
      ...pluginServer.env,
      ...userOverride.env,
    },
    
    // Merge env_vars lists
    env_vars: [
      ...(pluginServer.env_vars || []),
      ...(userOverride.env_vars || []),
    ],
  }
}

// During config loading
for (const [name, pluginServer] of pluginMcpServers) {
  const userOverride = userConfig.mcp_servers?.[name]
  if (userOverride && !userOverride.command && !userOverride.url) {
    // User provided partial override (env only) — merge with plugin config
    resolved[name] = resolveMcpServerConfig(pluginServer, userOverride)
  } else if (userOverride) {
    // User provided full override — use as-is
    resolved[name] = userOverride
  } else {
    resolved[name] = pluginServer
  }
}

Option B: Plugin user config / secrets manifest (long-term, more comprehensive)

Allow plugin manifests to declare configurable secret fields:

// .codex-plugin/plugin.json
{
  "mcpServers": "./.mcp.codex.json",
  "userConfig": {
    "workplus_access_token": {
      "type": "string",
      "sensitive": true,
      "required": false,
      "description": "WorkPlus API access token"
    }
  }
}

// .mcp.codex.json — reference user config via template
{
  "mcpServers": {
    "poka": {
      "env": {
        "WORKPLUS_ACCESS_TOKEN": "${userConfig.workplus_access_token}"
      }
    }
  }
}

User provides values via:

• ~/.codex/user-secrets.json (encrypted)
• Codex Desktop plugin settings UI
• Environment variables: CODEX_USER_CONFIG_WORKPLUS_ACCESS_TOKEN=xxx

// Template resolution
function resolveEnvTemplate(
  template: string,
  userConfig: Record<string, string>
): string {
  return template.replace(
    /\$\{userConfig\.(\w+)\}/g,
    (_, key) => userConfig[key] || ''
  )
}

Option C: Documented env_vars UX for Desktop

If env_vars is the intended solution, document and implement a clear path:

# ~/.codex/config.toml — documented pattern
[mcp_servers.poka]
# Partial env override for plugin-provided server
env.WORKPLUS_ACCESS_TOKEN = "user-token-here"

Or via environment:

# Documented: set plugin MCP secrets via environment
export CODEX_MCP_SECRETS_POKA_WORKPLUS_ACCESS_TOKEN="token"

Recommended Implementation Order

1. Immediate: Option A — partial env merge (2-3 lines of merge logic, fixes the reported issue)
2. Short-term: Option C — document the env_vars UX for Desktop users
3. Long-term: Option B — plugin user config manifest with secure storage in Desktop

Test Plan

1. Partial override merge: Plugin provides server with command/args/env. User adds [mcp_servers.poka.env] with just a token → server should start with merged config
2. Full override: User provides complete server definition → should override plugin entirely
3. No override: User provides nothing → plugin config should work as-is
4. Desktop UI: Plugin settings UI should show configurable fields and securely store values
5. Template resolution: ${userConfig.key} should resolve correctly in env templates

Impact Assessment

• Severity: P2 — plugin MCP servers with user secrets are awkward to configure
• Affected users: Plugin maintainers and users who need per-user credentials for MCP servers
• Fix complexity: Low for Option A (merge logic), Medium for Option B (manifest + UI)
• Risk: Minimal — additive change, backward compatible

Submission

Post as comment on: https://github.com/openai/codex/issues/24401

Ideally the solution should follow Anthropic's own standard for userConfig values w/ sensitive: true. This should support the system's keychain for secret storage.

See here for the full spec: https://code.claude.com/docs/en/plugins-reference#user-configuration