`claude mcp add` registers an MCP server with Claude Code, and the scope decides who gets it. Local scope is the default: the server loads only in the current project and stays private to you, stored in `~/.claude.json`. Project scope writes to `.mcp.json` at the project root, which the docs say to check into version control so your team gets the same servers. User scope also lives in `~/.claude.json` but loads in all your projects. If the same server name is in more than one scope, local wins over project, and project wins over user. Claude Code uses the whole entry from the winning scope and doesn't merge fields.
Who this is for
You're adding an MCP server to Claude Code and need to decide whether it's just for you, for this repo's whole team, or for every project on your machine.
The three scopes
| Scope | Flag | Loads in | Shared with team | Stored in |
|---|---|---|---|---|
| Local (default) | `--scope local` or no flag | Current project only | No | `~/.claude.json`, under that project's path |
| Project | `--scope project` | Current project only | Yes, via version control | `.mcp.json` in project root |
| User | `--scope user` | All your projects | No | `~/.claude.json` |
The basic remote form is `claude mcp add --transport http <name> <url>`. Add `--scope project` or `--scope user` to change where it lands.
Which to pick:
- Local for personal dev servers, experiments, or servers with credentials you don't want in version control (the docs' own suggested uses).
- Project when everyone on the repo needs the same server.
- User for personal utility servers you use across projects.
Pitfalls
- Pasting tokens into `.mcp.json`. It's committed. Use environment variable expansion: `${VAR}` expands to the variable's value, and `${VAR:-default}` falls back to a default when it isn't set.
- Expecting fields to merge. If a server exists in two scopes, the higher-precedence entry is used whole. A header you set only in the user entry won't show up when a local entry with the same name wins.
- Same name, different endpoints. Claude Code warns about the conflict in `claude mcp list` and `/mcp`. Keep the one you want and remove the others with `claude mcp remove <name> --scope <scope>`.
- Forgetting the approval step. In interactive sessions, Claude Code asks for approval before using project-scoped servers from `.mcp.json`. Until then, they show as pending.
- Reaching for SSE first. The docs mark the SSE transport as deprecated and say to use HTTP servers where available. `--transport sse` still works. See Streamable HTTP vs SSE.
How to check it
- Run `claude mcp list` to see each server and its health status.
- Run `claude mcp get <name>` for one server's details, including any pending approval.
- Open `.mcp.json` and confirm it contains `${VAR}` references, not secret values.
- If a server shows the wrong endpoint, check whether another scope defines the same name.
- If it connects but auth fails, that's a separate problem. See Claude vs Cursor MCP auth and static client IDs in mcp.json.
Where ShipKits fits
If you only need to pick a scope, the table above and the free templates at /free are enough. When you want a first desk day, the Day-1 Desk is a $12 pay-once first desk day: two seats (Day Desk + Reviewer Lite), one path-lock skill, a thin gate card, install.sh, and a ~90-minute sample run. Cheat Sheet for the skim checklist mindset.
Soft next step
Run `claude mcp list` now and move any server holding a secret out of `.mcp.json` or onto `${VAR}` references. Free starter files are at /free. When you want a first desk ready to install, the Day-1 Desk ($12) has it.