claude mcp add --scope: local vs project vs user, and which to pick

Originally published at https://aicoding-guide.com.

When you add an MCP server with claude mcp add, it is not obvious which --scope to pass. The names suggest the answer, but local and user are stored in the same file, which makes the distinction easy to miss.

Three things separate them: where they are stored, who they are shared with, and which one wins a name clash. In short: local (the default) for yourself in this project, project to share with your team, user for yourself everywhere.

Key point
What you will learn

• How the three scopes differ in storage and reach
• Why project writes .mcp.json and triggers an approval prompt
• Which scope wins when the same name appears in several

The three scopes side by side

Scope	Reach	Stored in	Shared with the team
local (default)	This project, you only	~/.claude.json, under that project's path	No
project	Everyone on the project	.mcp.json at the project root	Yes, through version control
user	All your projects	~/.claude.json	No

Both local and user land in ~/.claude.json. The difference is where inside it: the documentation says Claude Code stores a local server in ~/.claude.json under that project's path, so the same server won't appear in your other projects.

Omitting --scope gives you local. These two are equivalent:

claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Which to pick

Situation	Scope
A server with credentials you don't want in version control	local
An experimental configuration	local
Everyone on the team should get the same server	project
A server you use in every project (search, notes)	user

The documentation describes local's use cases the same way: personal development servers, experimental configurations, and servers with credentials you don't want in version control.

# Shared with the team (written to .mcp.json)
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# Available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project scope and .mcp.json

Adding with --scope project creates or updates .mcp.json at the project root.

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Commit that file to share the configuration. For how to add MCP servers in general, see Adding MCP servers to Claude Code.

Project scope comes with an approval prompt
The documentation states that for security reasons Claude Code prompts for approval in interactive sessions before using project-scoped servers from .mcp.json files. To reset those approval choices, run claude mcp reset-project-choices.

The cases where the prompt does not appear are documented too:

• In claude -p runs, Agent SDK sessions and cloud sessions, Claude Code can't show the prompt, so it loads project-scoped servers without asking
• It also skips the prompt in a session started in bypassPermissions mode with skipDangerousModePermissionPrompt set in user or managed settings

To keep a server out anyway, the documentation gives three options:

Option	Effect
Add it to disabledMcpjsonServers	Blocks it in every permission mode
Exclude project settings with --setting-sources (SDK: settingSources)	Project settings are not read at all
Start with --strict-mcp-config	Only the servers you pass with --mcp-config are used

When the same name appears twice

When a server is defined in more than one place, Claude Code connects once, using the definition from the highest-precedence source. The whole entry from that source is used; fields are not merged across scopes.

1. Local scope
2. Project scope
3. User scope
4. Plugin-provided servers
5. claude.ai connectors

The three scopes match duplicates by name. Define the same name in two scopes with different endpoints and Claude Code warns about the conflict in claude mcp list output and in /mcp.

Glossary
Scope: how far a piece of configuration reaches. For MCP it is set by two questions: just you or everyone, and this project or all of them.

Listing and removing

claude mcp list
claude mcp get <name>

Removing takes a scope:

claude mcp remove <name> --scope <scope>

Summary

• --scope defaults to local: yours, in this project only
• local and user share ~/.claude.json, but local is stored under the project's path
• project writes .mcp.json at the project root and travels through version control
• Project-scoped servers need approval in interactive sessions; reset with claude mcp reset-project-choices
• On a name clash the order is local, project, user, plugin, connector — and only one definition is used