claude-code - 💡(How to fix) Fix [BUG] claude mcp add -e <KEY=VAL> <name> -- <cmd> still fails in 2.1.150 (the syntax printed by --help)

Preflight

• Reproduced on Claude Code 2.1.150, macOS (Darwin 25.5.0).
• Same bug as #23365 (closed 2026-03 as stale, never fixed) and the doc dup #29221 (closed as duplicate of #23365). Both auto-closed by inactivity, not by a fix. The defect and the misleading help text are still present today, so filing a fresh report.

What's wrong

The example syntax printed by claude mcp add --help does not work:

# Add stdio server with environment variables:
claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server

Running it verbatim:

$ claude mcp add -s user -e FOO=bar testparser -- echo hello
Invalid environment variable format: testparser, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

The -e/--env option appears to be defined as variadic and greedily consumes the next positional argument (the server name) as a second env-var value.

Workaround

Either reorder so positional args come before the name:

$ claude mcp add -s user -e FOO=bar -- testparser echo hello
Added stdio MCP server testparser with command: echo hello to user config

…or sidestep the parser entirely with add-json:

$ claude mcp add-json -s user testparser \
    '{"type":"stdio","command":"echo","args":["hello"],"env":{"FOO":"bar"}}'
Added stdio MCP server testparser to user config

Steps to reproduce

claude --version                       # 2.1.150
claude mcp add -s user -e FOO=bar testparser -- echo hello

Expected

The example printed by claude mcp add --help should add the server (it is the documented, canonical syntax — both inside the CLI and historically in the public docs, see #29221).

Suggested fix (pick one)

1. Make -e/--env non-variadic (repeatable single-value, as Docker's -e is). This is what users expect from the -e KEY=VAL shape and what the help example implies.
2. Failing that, update the help text in claude mcp add --help to show the name-first form (claude mcp add -s user my-server -e FOO=bar -- npx my-mcp-server), so the printed example actually works.

(1) is the user-friendly fix; (2) is the bare minimum so people stop hitting this. Right now the only in-CLI guidance to a working invocation is the cryptic error message.

Environment

• Claude Code: 2.1.150
• OS: macOS 26 (Darwin 25.5.0)
• Shell: bash

Related

• #23365 — original bug report, closed stale
• #29221 — docs-side report, closed as duplicate of #23365