Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] MCP docs do not document that `workspace` is a reserved server name [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#56154•Fetched 2026-05-05 05:56:46
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4

Code Example

> {
>   "mcpServers": {
>     "shared-server": {
>       "command": "/path/to/server",
>       "args": [],
>       "env": {}
>     }
>   }
> }
>
RAW_BUFFERClick to expand / collapse

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:

{
  "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:

PageContext
https://code.claude.com/docs/en/mcpPrimary 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/hooksDocuments 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/hooksStates that the MCP tool prefix comes from the configured server name
https://code.claude.com/docs/en/agent-sdk/mcpDocuments 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.

extent analysis

TL;DR

Update the MCP setup documentation to include a note about reserved server names, specifically that workspace is reserved and cannot be used as a custom MCP server name.

Guidance

  • Add a note near the claude mcp add syntax block and the .mcp.json examples in the MCP setup guide to warn users about the reserved server name workspace.
  • List any other reserved MCP server names in the same section to provide a canonical reference for naming rules.
  • Update the documentation to explain the migration behavior for existing configurations that use the reserved name workspace, including renaming the server and updating related MCP tool matchers or allowlists.
  • Review the affected pages (MCP setup, hooks, agent-sdk hooks, and agent-sdk MCP) to ensure consistent documentation of the mcp__<server>__<tool> naming pattern and the impact of server name changes.

Example

No code snippet is necessary for this documentation update.

Notes

The update should be applied to the primary MCP setup guide and other affected pages to ensure consistent documentation and avoid confusion for users.

Recommendation

Apply the workaround by updating the documentation to include the reserved server name note and migration guidance, as this will help users understand the naming restriction and avoid issues with their MCP configurations.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#API middleware#SSR setup#ISR setup#authentication setup#request error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] MCP docs do not document that `workspace` is a reserved server name [1 participants]