Document how to use shell environment variables in MCP server configuration

[PaulRBerg]

What is the type of issue?

Documentation is missing

What is the issue?

There is no documentation explaining how to reference shell environment variables when configuring MCP servers in config.toml. Users need to pass API keys and other secrets to MCP servers, but it's unclear which syntax works:

Option 1 - Simple variable reference:

[mcp_servers.context7]
  args = ["-y", "@upstash/context7-mcp", "--api-key", "$API_KEY_CONTEXT7_MCP"]
  command = "npx"

Option 2 - Brace-wrapped variable reference:

[mcp_servers.context7]
  args = ["-y", "@upstash/context7-mcp", "--api-key", "${API_KEY_CONTEXT7_MCP}"]
  command = "npx"

The documentation should clarify:

1. Which syntax is supported (or if both work)
2. Whether variable expansion happens at config load time or command execution time
3. Any gotchas with quoting or escaping

[!IMPORTANT] Users should also be aware that they may need to set shell_environment_policy.ignore_default_excludes to true for environment variables to be passed through correctly. See #3064 for related discussion.

Where did you find it?

• https://github.com/openai/codex - No mention of environment variable syntax in README
• https://github.com/openai/codex/blob/main/codex-rs/config.md - Configuration docs don't cover this use case

[github-actions[bot]]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #7367

Powered by Codex Action

[PaulRBerg]

Issue #7367 is related but not quite the same. I am asking to document how to load env vars.