[DOCS] Conflicting Definitions of "Local Scope" in Settings vs. MCP Documentation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://code.claude.com/docs/en/settings - https://code.claude.com/docs/en/mcp

Section/Topic

• Settings Page: The "Configuration scopes" table/section. - MCP Page: The "MCP installation scopes" -> "Local scope" section.

Current Documentation

From Settings (Configuration scopes):

"Local | .claude/.local. files | You, in this repository only | No (gitignored)"

From MCP (Local scope):

"Local-scoped servers represent the default configuration level and are stored in ~/.claude.json under your project's path."

What's Wrong or Missing?

There is a contradiction in how "Local Scope" is defined and where the data is stored:

1. Settings Definition: Defines "Local" as files physically located inside the repository (e.g., .claude/settings.local.json) that are gitignored.
2. MCP Definition: Defines "Local" as configuration stored in the user's home directory (~/.claude.json), using the project path as a key.

This creates confusion for users trying to manage configuration files. A user reading the Settings page expects "Local" changes to result in a file within their project directory, but adding a local MCP server modifies a global file in their home directory instead.

Suggested Improvement

The terminology should be clarified to distinguish between "Local Project Settings" and "Local MCP Servers," or the MCP documentation should explicitly note this deviation from the standard scope definition found in the Settings page.

Option A (Clarification in MCP Docs):
Update the MCP "Local scope" section to explicitly state:

"Unlike general local settings which are stored in the project directory, Local-scoped MCP servers are stored in your global ~/.claude.json file, keyed to your specific project path. This keeps them private to you without creating files in the project folder."

Option B (Unification in Settings Docs):
Update the "Configuration scopes" table in the Settings page to reflect that "Local" storage locations vary by feature (Settings vs. MCP).

Impact

High - Prevents users from using a feature

Additional Context

• Mental Model Conflict: Users typically associate "Local" with the current working directory. The MCP implementation behaves more like "User-scoped but project-specific."
• Version Control Implications: The Settings page implies "Local" files exist in the repo but are ignored by git. The MCP page implies "Local" files do not exist in the repo at all.