Document how to use shell environment variables in MCP server configuration

Open 💬 3 comments Opened Dec 3, 2025 by 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?

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗