[DOCS] `claude mcp add-from-claude-desktop` docs do not document the v2.1.205 invalid-name reporting and partial-import behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "Import MCP servers from Claude Desktop" section of the MCP reference (the <Steps> block that introduces claude mcp add-from-claude-desktop, the surrounding tip list that describes the macOS/WSL availability and name-conflict behavior, and the "Managing your servers" / "The server name workspace is reserved" paragraphs that document related name-validation rules). The cross-reference from https://code.claude.com/docs/en/desktop under the "MCP servers from the Claude Desktop chat app" note that links to that section should be checked in the same pass.

Current Documentation

The "Import MCP servers from Claude Desktop" section in mcp.md currently says:

## Import MCP servers from Claude Desktop If you've already configured MCP servers in Claude Desktop, you can import them: <Steps> <Step title="Import servers from Claude Desktop"> ``bash theme={null} # Basic syntax claude mcp add-from-claude-desktop ` </Step> <Step title="Select which servers to import"> After running the command, you'll see an interactive dialog that allows you to select which servers you want to import. </Step> <Step title="Verify the servers were imported"> `bash theme={null} claude mcp list ` </Step> </Steps> <Tip> Tips: * This feature only works on macOS and Windows Subsystem for Linux (WSL) * It reads the Claude Desktop configuration file from its standard location on those platforms * Use the --scope user flag to add servers to your user configuration * Imported servers keep the same names as in Claude Desktop * If servers with the same names already exist, they get a numerical suffix (for example, server_1`) </Tip>

The page's only other naming rule is the unrelated workspace reservation under "Managing your servers":

The server name workspace is reserved for internal use. If your configuration defines a server with that name, Claude Code skips it at load time and shows a warning asking you to rename it.

The "Add a local stdio server" / "Add an HTTP server" <Note> only documents the --env/name parsing interaction:

--env accepts multiple KEY=value pairs. If the server name comes directly after --env, the CLI reads the name as another pair and rejects it, so place at least one other option between --env and the server name, as in the examples above.

desktop.md line 691 cross-references the section without adding any naming caveats:

The standalone CLI does not read claude_desktop_config.json. On macOS and WSL, run claude mcp add-from-claude-desktop to copy those servers into ~/.claude.json. See Import MCP servers from Claude Desktop for the import flow and scope options.

The changelog at https://code.claude.com/docs/en/changelog.md line 22 records the v2.1.205 fix:

* Fixed claude mcp add-from-claude-desktop getting stuck when a server name contains unsupported characters; invalid names are now reported and remaining servers still import

What's Wrong or Missing?

A. The "Import MCP servers from Claude Desktop" section never defines what counts as an "invalid" or "unsupported" server name

The <Tip> only documents the duplicate-name suffix behavior and says imported servers "keep the same names as in Claude Desktop." Nothing on the page tells a reader which characters are accepted in an MCP server name, why some names are "unsupported," or how Claude Desktop's free-form name field can produce a name that Claude Code rejects. A user running claude mcp add-from-claude-desktop after editing claude_desktop_config.json by hand has no docs entry to predict which keys will be skipped.

B. The v2.1.205 error-reporting behavior is not described anywhere outside the changelog

Before v2.1.205, encountering a server with unsupported characters in its name left the importer in a state that the docs could plausibly describe as "stuck" - the user would see no progress and no diagnostic. After v2.1.205, the command reports the invalid names explicitly. The "Import MCP servers from Claude Desktop" section never describes this error path, so a user who sees the report has nothing in the docs that explains what the message means or what to do about the offending entry in claude_desktop_config.json.

C. The partial-success / "remaining servers still import" behavior is undocumented

The v2.1.205 entry's most useful guarantee is that the importer no longer aborts on the first bad name - it skips the invalid entries and continues with the rest. The current <Steps> block implies the command either succeeds for everything you selected or fails wholesale, and never tells the reader that a partially-failed import still imports every valid name. Users who try to import many servers at once have no way to predict that one bad name will not stop the rest.

D. The "duplicate name" tip and the "invalid name" path are both name-handling cases but live in different mental buckets

The current <Tip> calls out the "if servers with the same names already exist, they get a numerical suffix" rule but never cross-references the new "invalid name" path. After v2.1.205 both paths produce different observable outcomes (a _1 suffix versus a per-server error), and the docs should treat them as siblings: a single short paragraph under the import section that lists the three observable name outcomes (kept as-is, suffixed on collision, reported and skipped when invalid).

E. The cross-reference from desktop.md does not warn Desktop migrators about the new behavior

desktop.md is the page a Claude Desktop user is most likely to read first when they switch to the CLI. Its "MCP servers from the Claude Desktop chat app" <Note> says only that claude mcp add-from-claude-desktop "copy those servers into ~/.claude.json" and links to the import section. It does not mention the v2.1.205 invalid-name behavior, so a Desktop user whose claude_desktop_config.json contains a name the CLI does not accept gets no hint from the migration page that the importer will report the bad key rather than hang.

Suggested Improvement

Extend the "Import MCP servers from Claude Desktop" section in mcp.md so the tip list and the per-step text cover the v2.1.205 invalid-name and partial-success behavior, for example:

<Tip> Tips: This feature only works on macOS and Windows Subsystem for Linux (WSL) It reads the Claude Desktop configuration file from its standard location on those platforms Use the --scope user flag to add servers to your user configuration Imported servers keep the same names as in Claude Desktop If servers with the same names already exist, they get a numerical suffix (for example, server_1) Server names that contain characters Claude Code does not accept in MCP server names are reported as invalid, then skipped, and the rest of the selected servers are still imported. Rename the offending entry in claude_desktop_config.json to a name that uses only supported characters, then re-run claude mcp add-from-claude-desktop to import it </Tip>

Add one sentence to the surrounding prose (either as a closing <Note> under the <Steps> block or inside the second step) that explicitly states the partial-success behavior, for example:

{/ min-version: 2.1.205 /}As of Claude Code v2.1.205, an invalid server name is reported in the import dialog and the import continues with the remaining servers instead of stopping. Earlier versions of claude mcp add-from-claude-desktop could appear to hang when claude_desktop_config.json contained a name with unsupported characters.

Cross-link the new tip to the existing "Managing your servers" paragraph that documents the workspace reservation, so the page presents all three name-handling cases (invalid characters, reserved workspace, duplicate-name suffix) as a single coherent surface.

Update the desktop.md "MCP servers from the Claude Desktop chat app" <Note> to mention the new behavior in one short sentence and link to the import section:

The standalone CLI does not read claude_desktop_config.json. On macOS and WSL, run claude mcp add-from-claude-desktop to copy those servers into ~/.claude.json. Server names that contain characters Claude Code does not accept are reported and skipped while the rest of the servers are still imported. See Import MCP servers from Claude Desktop for the import flow and scope options.

Impact

Medium - Makes feature difficult to understand

Additional Context

v2.1.205 is the release that added the documented behavior. Other Claude Code pages already use the {/* min-version: 2.1.<N> */} inline annotation pattern for release-scoped fixes, so the import section can adopt the same shape.

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | "Import MCP servers from Claude Desktop" section and the related "Managing your servers" / reserved-name paragraphs |
| https://code.claude.com/docs/en/desktop | "MCP servers from the Claude Desktop chat app" <Note> that links to the import section |

Total scope: 2 pages affected.

Related but distinct: The workspace reservation lives next to the affected import section, but is a different name-handling rule and should remain separate from this report. The v2.1.128 changelog line that introduced the workspace reservation, the v2.1.205 changelog line that introduced the invalid-name reporting, and the existing duplicate-name suffix in the <Tip> together describe the three observable name outcomes of claude mcp add-from-claude-desktop. A future docs pass should treat all three as one surface, but this issue is scoped to the v2.1.205 fix.