Document MCP env_vars for secret-manager session tokens like BW_SESSION

Summary

Codex MCP subprocesses did not inherit the shell's secret-manager session environment by default. In this case an MCP server that resolved AGENTMAIL_API_KEY through Bitwarden appeared configured/enabled, but the model could not reliably discover/call the server's tools until I explicitly passed BW_SESSION through env_vars.

This is probably working as designed from a strict environment-isolation perspective, but the failure mode was hard to diagnose: codex mcp list / codex mcp get showed the server as enabled, and the same wrapper worked from the shell. A clearer warning or docs note would help MCP servers that resolve credentials from CLI secret managers.

Environment

• Codex CLI: 0.122.0
• macOS: 15.6.1
• Node used by the MCP scripts: v25.8.2
• MCP transport: stdio
• Secret manager: Bitwarden CLI (bw)

Repro Shape

1. Configure a stdio MCP server whose wrapper resolves its API key from either AGENTMAIL_API_KEY or Bitwarden CLI:

[mcp_servers.AgentMail]
command = "/path/to/agentmail-mcp.sh"
args = []
startup_timeout_sec = 20
default_tools_enabled = true
default_tools_approval_mode = "approve"
enabled_tools = ["list_inboxes"]

1. In the interactive shell, Bitwarden is unlocked and the wrapper works:

bw status
/path/to/agentmail-mcp.sh   # raw MCP initialize/tools/list works

1. In Codex, the server appears enabled, but native model calls to the server/tool are unavailable or fail because the MCP subprocess sees Bitwarden as locked.

A diagnostic MCP resource inside the subprocess showed the important difference:

{
  "hasAgentMailApiKeyEnv": false,
  "home": "/Users/...",
  "pathHasHomebrew": true,
  "bitwardenStatusExit": 0,
  "bitwardenStatusStdout": "{...\"status\":\"locked\"}"
}

1. Passing the session variables through fixes it:

[mcp_servers.AgentMail]
command = "/path/to/agentmail-mcp.sh"
args = []
startup_timeout_sec = 20
default_tools_enabled = true
default_tools_approval_mode = "approve"
env_vars = ["AGENTMAIL_API_KEY", "BW_SESSION"]
enabled_tools = ["list_inboxes"]

[mcp_servers.AgentMail.env]
HOME = "/Users/..."
PATH = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

After that, native Codex MCP calls to the tool succeed.

Expected

Either:

• Docs explicitly call out that secret-manager session variables like BW_SESSION must be passed through with env_vars; or
• codex mcp get/list / startup diagnostics make it easier to see that a configured MCP server's runtime environment differs from the launching shell in a way that can lock secret-manager access.

Actual

The server looked enabled from codex mcp list, but the actionable cause was only visible after building a custom diagnostic MCP resource.

Notes

No raw credentials were stored in config.toml; env_vars was sufficient and is the right fix once discovered.