[DOCS] Contradictory Syntax Requirements for `claude mcp add` between Documentation Text and Interactive Code Generator

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Installing MCP servers" section (specifically the "Important: Option ordering" note) and the "Popular MCP servers" interactive table component (MCPServersTable).

Current Documentation

The documentation text states:

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.

However, the logic within the MCPServersTable component generates commands with the following structure:
claude mcp add ${serverSlug} --transport http ${server.urls.http}

What's Wrong or Missing?

There is a direct contradiction between the instructions and the provided copy-paste examples. The text explicitly warns that options must come before the server name to avoid conflicts, but the interactive generator puts the name (serverSlug) immediately after add and before the flags (like --transport).

This creates a high likelihood of user error, especially for stdio-based servers where the -- separator is used. If a user follows the pattern generated by the table, they may encounter "Unknown flag" errors or find that their flags are being incorrectly passed to the MCP server instead of Claude Code.

Suggested Improvement

Update the generateClaudeCodeCommand logic within the MCPServersTable script to align with the documented strict ordering.

Suggested change for HTTP/SSE transports:
From:
return "claude mcp add ${serverSlug} --transport http ${server.urls.http}";
To:
return "claude mcp add --transport http ${serverSlug} ${server.urls.http}";

Suggested change for stdio transport:
From:
const baseCommand = "claude mcp add ${serverSlug} --transport stdio";
To:
const baseCommand = "claude mcp add --transport stdio ${serverSlug}";

Impact

High - Prevents users from using a feature

Additional Context

This issue is of Major severity because it affects the primary onboarding path for users attempting to extend Claude Code's capabilities. Providing a copy-paste command that violates the "Important" warning immediately below it undermines the authority of the documentation and leads to broken configurations.

Internal logic reference from the source:

const generateClaudeCodeCommand = server => {
  // ...
  if (server.urls.http) {
    return `claude mcp add ${serverSlug} --transport http ${server.urls.http}`;
  }
  // ...
  const baseCommand = `claude mcp add ${serverSlug} --transport stdio`;
  return envFlags ? `${baseCommand} ${envFlags} -- ${server.urls.stdio}` : `${baseCommand} -- ${server.urls.stdio}`;
};