[DOCS] Major terminology inconsistency for "Local" scope between Settings and MCP documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/settings#configuration-scopes - https://code.claude.com/docs/en/mcp#local-scope - https://code.claude.com/docs/en/mcp#mcp-installation-scopes

Section/Topic

The definition of "Local Scope" and its physical storage location.

Current Documentation

• Settings Page (/docs/en/settings): Defines "Local" scope as project-level files that are not committed to git. It lists the location as: .claude/*.local.* files (e.g., .claude/settings.local.json) and states they are "gitignored."
• MCP Page (/docs/en/mcp): Defines "Local" scope as private global configuration. It states: "Local-scoped servers... are stored in ~/.claude.json under your project's path. These servers remain private to you and are only accessible when working within the current project directory."

What's Wrong or Missing?

The term "Local" is being used to describe two different storage behaviors depending on the feature being discussed (General Settings vs. MCP).

For General Settings, "Local" means the file physically resides inside the project folder (but is ignored by git). For MCP, "Local" means the configuration physically resides in the user's home directory (global config file) but is logically keyed to a specific project path.

This inconsistency is confusing for developers trying to manage their configurations. If a user wants to "clean up their local config," they won't know if they need to delete a file in their repository or an entry in their home directory. Furthermore, the MCP page states that previous "project" scope was renamed to "local" (Version 2.0.49), which directly conflicts with the Settings page where "Project" and "Local" are two distinct, hierarchical tiers.

Suggested Improvement

Harmonize the terminology across all pages.

• Recommendation A: Use the Settings page definition as the standard. "Local" should always refer to files residing in the project directory that are gitignored (.claude/settings.local.json).
• Recommendation B: Rename the current MCP "Local" scope to something more descriptive of its physical location, such as "Project-Private" or "User-Project-Scoped."
• Documentation Update: Explicitly clarify on the MCP page that these configurations are stored in ~/.claude.json to distinguish them from repository-resident files. Ensure the hierarchy table at https://code.claude.com/docs/en/settings#how-scopes-interact accurately reflects how MCP's unique storage mechanism fits into the precedence order.

Impact

High - Prevents users from using a feature

Additional Context

• In the transition to Version 2.0.49, the MCP scope was renamed from "project" to "local." This appears to be the source of the collision with the newer .claude/settings.local.json file structure introduced for general settings.
• Most CLI tools (like Prettier or VS Code) use "Local" to mean "local to the workspace/repository." Following this convention for MCP would mean moving those configs into the .claude/ folder. If they must remain in ~/.claude.json for security or architectural reasons, the "Local" label should be changed to avoid the collision.