[DOCS] CLI Syntax Inconsistency regarding `--` separator for `claude mcp add`

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/cli-reference - https://code.claude.com/docs/en/mcp

Section/Topic

The CLI Reference table for the claude mcp command.

Current Documentation

In the CLI Reference (docs/en/cli-reference.md), the table entry says:

| claude mcp | Configure Model Context Protocol (MCP) servers | See the [Claude Code MCP documentation](/en/mcp). |

In the MCP Detailed Guide (docs/en/mcp.md), it provides a strict requirement:

Important: Option ordering All options (--transport, --env, --scope, --header) must come before the server name. The -- (double dash) then separates the server name from the command and arguments that get passed to the MCP server.

What's Wrong or Missing?

The CLI Reference is the primary destination for users checking command syntax. However, it fails to mention the mandatory use of the -- separator or the specific required order of flags for mcp add.

Because many modern CLI tools are flexible with flag ordering, users relying solely on the CLI Reference table are likely to encounter "Connection closed" or parsing errors by placing flags after the server name or omitting the double dash entirely. The strictness of this syntax (requiring flags before the positional argument and a separator for sub-process arguments) makes it a critical detail that shouldn't be buried in the long-form guide.

Suggested Improvement

Add a footnote or an explicit syntax reminder to the claude mcp entry in the CLI commands table.

Suggested Text for the CLI Reference Table:
| Command | Description | Example |
| :--- | :--- | :--- |
| claude mcp | Configure MCP servers. Note: When adding servers, flags must precede the name, and arguments require a -- separator. | claude mcp add --transport stdio my-server -- npx server-cmd |

Additionally, add a brief "Note on -- separator" under the CLI flags section to explain that it is used to stop Claude from parsing flags and pass them to the underlying MCP server or bash process.

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: The MCP guide correctly emphasizes this, but the high-level reference does not.
• Examples from other projects: This is similar to how npm run <script> -- <args> or docker run <image> <args> works; however, because claude is an agentic wrapper, the risk of "flag leakage" is higher if the separator is forgotten. Users coming from more permissive CLIs will likely trip over the "Options must come BEFORE the name" rule.