bug: MCP server headers silently fail env var substitution with $VAR syntax

[clouatre]

Checks

• I have searched github.com/aws/amazon-q-developer-cli/issues and there are no duplicates of my issue
• I have run q doctor in the affected terminal session
• I have run q restart and replicated the issue again

Operating system

macOS 26.3.0 (Apple M3 Pro)

Expected behaviour

Environment variable substitution in MCP server headers should work with $VAR_NAME or ${VAR_NAME} syntax, consistent with the env block in the same config and with other MCP clients (Cursor, Goose).

Actual behaviour

The headers field requires ${env:VAR_NAME} syntax. Using $VAR_NAME (same syntax that works in the env block) silently passes the literal string instead of the resolved value. The remote MCP server rejects it with "API key is not configured or invalid" -- no warning from the CLI.

Steps to reproduce

1. Create an agent config with a remote MCP server using $VAR syntax in headers:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "env": {
        "CONTEXT7_API_KEY": "$CONTEXT7_API_KEY"
      },
      "headers": {
        "CONTEXT7_API_KEY": "$CONTEXT7_API_KEY"
      },
      "disabled": false
    }
  }
}

2. Run kiro-cli chat --agent my-agent --trust-all-tools
3. Ask the model to call a Context7 tool
4. Observe: "API key is not configured or invalid"
5. Change headers to "${env:CONTEXT7_API_KEY}" -- works

The env block uses $VAR and works. The headers block requires ${env:VAR} but nothing documents this. The ${env:VAR} syntax is only discoverable by reading the source (substitute_env_vars in crates/chat-cli/src/mcp_client/client.rs).

Other MCP clients for comparison:

• Cursor: ${VAR_NAME}
• Goose: $VAR_NAME
• Kiro/Q CLI: ${env:VAR_NAME} (undocumented)

Environment

version: 1.26.1
hash: 9d6226020f759dab8f2fad1b1d7179a50f1479ef
date: 2026-02-16T21:58:46.784323Z
variant: full
os: macOS 26.3.0
chip: Apple M3 Pro
shell: /bin/zsh 5.9
terminal: Kitty
install-method: brew