aws / aws/amazon-q-developer-cli

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

Open
#3,646 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.