[DOCS] MCP docs do not document that `workspace` is a reserved server name

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Installing MCP servers / .mcp.json server naming rules

Current Documentation

The docs currently say:

claude mcp add --transport http <name> <url> claude mcp add --transport sse <name> <url> claude mcp add [options] <name> -- <command> [args...]

And later, in the project-scope example:

The resulting .mcp.json file follows a standardized format: ``json { "mcpServers": { "shared-server": { "command": "/path/to/server", "args": [], "env": {} } } } ``

Related pages also describe MCP tool names as coming directly from the configured server name:

MCP tools follow the naming pattern mcp__<server>__<tool>

The server name comes from the key you use in the mcpServers configuration.

What's Wrong or Missing?

As of v2.1.128, workspace is a reserved MCP server name, but the MCP setup docs do not mention that restriction.

That leaves two gaps:

A. New configurations have no naming warning

The claude mcp add and .mcp.json examples treat the server name as an unrestricted placeholder, so readers are not warned that workspace is now disallowed.

B. Existing configurations have no migration guidance

The docs do not explain that existing servers named workspace are skipped with a warning, or that users need to rename the server and update any related MCP tool matchers or allowlists that reference that server name.

Suggested Improvement

Add a note in https://code.claude.com/docs/en/mcp near the first claude mcp add syntax block and again near the .mcp.json examples:

Reserved MCP server names: workspace is reserved and cannot be used as a custom MCP server name. If an existing local, user, or project MCP configuration uses workspace as the server name, Claude Code skips that server and logs a warning. Rename the server to a non-reserved name, then update any hook matchers, allowlists, or other references that use the old mcp__workspace__... tool prefix.

If there are other reserved MCP server names, list them in the same section so users have one canonical naming-rules reference.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary setup page for claude mcp add, claude mcp add-json, and .mcp.json examples that currently omit the reserved-name rule |
| https://code.claude.com/docs/en/hooks | Documents the mcp__<server>__<tool> naming pattern; users renaming a workspace server need to update matcher patterns accordingly |
| https://code.claude.com/docs/en/agent-sdk/hooks | States that the MCP tool prefix comes from the configured server name |
| https://code.claude.com/docs/en/agent-sdk/mcp | Documents the same mcp__<server-name>__<tool-name> convention for SDK users |

Total scope: 4 pages affected

This appears to need a v2.1.128 documentation update so the naming restriction and migration behavior are documented in the primary MCP setup guide.