aws / aws/amazon-q-developer-cli
bug: MCP server headers silently fail env var substitution with $VAR syntax
- Dominant language
- Rust
- Stars
- 2k
- Forks
- 439
- PR merge metrics
- No merged PRs in 30d
Description
## Checks
- [x] I have searched [github.com/aws/amazon-q-developer-cli/issues](https://github.com/aws/amazon-q-developer-cli/issues?q=) and there are no duplicates of my issue
- [x] I have run `q doctor` in the affected terminal session
- [x] 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:
```json
{
"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
```yaml
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
```
Contributor guide
Assessment
This issue has not been assessed yet.