Docs: Discrepancy in `claude mcp add` scope storage locations

### Title: Docs: Discrepancy in claude mcp add scope storage locations

Issue Description

The official documentation for Model Context Protocol (MCP) server configuration scopes does not accurately reflect the actual file storage locations used by the claude mcp add command. Specifically, the behavior for user and local scopes differs from the documented hierarchy of settings.json files, leading to user confusion.

The current documentation implies that user-level configurations are stored in ~/.claude/settings.json and local project configurations in .claude/settings.local.json. However, testing reveals that claude mcp commands for these scopes instead modify the legacy ~/.claude.json file.

Steps to Reproduce

I ran the following series of tests in an empty directory (~/Desktop/test) to verify the behavior of each --scope flag:

➜  Desktop cd test
➜  test claude mcp add playwright npx @playwright/mcp@latest
Added stdio MCP server playwright with command: npx @playwright/mcp@latest to local config
File modified: /Users/user/.claude.json [project: /Users/user/Desktop/test]

➜  test claude mcp remove playwright
Removed MCP server "playwright" from local config
File modified: /Users/user/.claude.json [project: /Users/user/Desktop/test]

➜  test claude mcp add playwright --scope project npx @playwright/mcp@latest
Added stdio MCP server playwright with command: npx @playwright/mcp@latest to project config
File modified: /Users/user/Desktop/test/.mcp.json

➜  test claude mcp remove playwright
Removed MCP server "playwright" from project config
File modified: /Users/user/Desktop/test/.mcp.json

➜  test claude mcp add playwright --scope user npx @playwright/mcp@latest
Added stdio MCP server playwright with command: npx @playwright/mcp@latest to user config
File modified: /Users/user/.claude.json

➜  test claude mcp remove playwright
Removed MCP server "playwright" from user config
File modified: /Users/user/.claude.json

➜  test claude mcp add playwright --scope local npx @playwright/mcp@latest
Added stdio MCP server playwright with command: npx @playwright/mcp@latest to local config
File modified: /Users/user/.claude.json [project: /Users/user/Desktop/test]

➜  test claude mcp remove playwright
Removed MCP server "playwright" from local config
File modified: /Users/user/.claude.json [project: /Users/user/Desktop/test]

Expected Behavior

Based on the MCP documentation and the Settings documentation, I expected the following file modifications:

• --scope project: Modifies ./.mcp.json (This works as expected).
• --scope user: Modifies ~/.claude/settings.json.
• --scope local (or default): Modifies ./.claude/settings.local.json.

Actual Behavior

The tests above confirm the following actual behavior:

• --scope project: Correctly modifies ./.mcp.json.
• --scope user: Modifies ~/.claude.json.
• --scope local (or default): Also modifies ~/.claude.json, but the CLI output indicates it is linked to a specific project.

The local scope's behavior is particularly confusing, as it uses a global file to store a project-specific configuration.

Suggested Resolution

Please update the official documentation on the Connect Claude Code to tools via MCP page and any related settings pages to reflect the tool's actual behavior.

A clear, accurate summary table in the documentation would be extremely helpful for users, like the one below:

| Scope | claude mcp add Command | Storage File | Purpose & Behavior |
| :--- | :--- | :--- | :--- |
| Project | --scope project | ./.mcp.json | Team Sharing. Stored inside the project. Commit this file to Git to share the server with your team. |
| User | --scope user | ~/.claude.json | Personal & Global. Stored in your home directory. The server is available to you in all of your projects. |
| Local | --scope local <br/> (or default) | ~/.claude.json | Personal & Project-Specific. Stored in your home directory, but internally linked to the current project. The server is only available to you when working in this specific project. |

This clarification will help users correctly manage their MCP server configurations and understand the distinction between the newer settings.json hierarchy and the legacy .claude.json file.

Thank you for your excellent work on Claude Code