[DOCS] Contradiction between MCP option ordering rule and code examples

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

"Important: Option ordering" note, "Local scope" examples, and "Project scope" examples.

Current Documentation

The documentation contains an explicit warning note:

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. For example: * claude mcp add --transport stdio myserver -- npx server → runs npx server

However, the "Local scope" and "Project scope" sections provide the following examples:

• claude mcp add stripe --transport http https://mcp.stripe.com
• claude mcp add paypal --scope project https://mcp.paypal.com/mcp

What's Wrong or Missing?

The documentation is internally inconsistent. The instruction note explicitly states that flags like --transport or --scope must come before the server name (stripe or paypal). However, the very next code examples show the server name being provided immediately after add, with the flags following it.

This is confusing for users who may find their commands failing due to CLI parsing logic if the "Important" note is the correct behavior, or they may ignore the note if the examples seem more intuitive.

Suggested Improvement

Update the examples in the "Local scope" and "Project scope" sections to match the ordering rule defined in the "Important: Option ordering" note.

Suggested changes:

Change:
claude mcp add stripe --transport http https://mcp.stripe.com
To:
claude mcp add --transport http stripe https://mcp.stripe.com

Change:
claude mcp add paypal --scope project https://mcp.paypal.com/mcp
To:
claude mcp add --scope project paypal https://mcp.paypal.com/mcp

Impact

High - Prevents users from using a feature

Additional Context

This inconsistency appears to be a regression or a mismatch between the documentation and the intended CLI signature. In many Node.js-based CLIs, positional arguments (the server name) must follow all options to avoid being swallowed or misparsed, which justifies why the "Important" note exists. Ensuring the examples reflect this prevents users from encountering Unknown argument errors or misconfigured servers.