Claude Code connects once, using the definition from the highest-precedence source, and uses that entry whole: fields are not merged across scopes. The order, from the documentation on 2026-09-08:
The three scopes match duplicates by name. Plugins and connectors match by endpoint, so one pointing at the same URL or command as a server above it is treated as a duplicate of it even under a different name.
| Scope | Written to | Visible in |
|---|---|---|
local (default) | ~/.claude.json | only you, only the directory you added it in |
project | .mcp.json at the repository root | everyone who clones the repository, after approval |
user | ~/.claude.json | only you, every project |
The default being local is the most common reason a server that was definitely added is
definitely not there. It is per directory. -s is the short form of --scope.
claude mcp add --scope user invoice -- node /abs/path/dist/index.js
claude mcp list # run it in the directory you are missing the server fromA server defined in a repository's .mcp.json is not started until you approve it. Until
then claude mcp list and claude mcp get <name> show it as pending
approval and do not connect to it. As of v2.1.196, those two commands read .mcp.json
approvals only from settings files that are not checked into the repository, until you trust the
workspace by running claude in it and accepting the trust dialog. A cloned repository
cannot approve its own servers: enableAllProjectMcpServers or
enabledMcpjsonServers committed to the project's .claude/settings.json is
ignored in an untrusted folder.
That is the right default. A config file in a repository is an instruction to run a program, and cloning a repository should not be enough to do it.
Toggling a server off in Claude Code records the choice per project in ~/.claude.json,
in one of two lists covering disjoint sets of servers: disabledMcpServers, an opt-out list
for user-configured and plugin servers, and a separate pair,
enabledMcpjsonServers and disabledMcpjsonServers, which control approval of
servers defined in a project's .mcp.json. Those two mechanisms are unrelated, which is why
a server can be both approved and disabled, or neither.
VS Code does the same thing for a different reason: the enabled state is stored separately from the
server configuration in mcp.json, so turning a server off locally does not modify a file
your team shares.
| Client | Project layer | Global layer |
|---|---|---|
| Cursor | .cursor/mcp.json | ~/.cursor/mcp.json |
| VS Code | .vscode/mcp.json | user profile, via MCP: Open User Configuration |
| Cline | none documented | ~/.cline/mcp.json for the CLI, panel settings for the extension |
| Windsurf | none documented | ~/.codeium/windsurf/mcp_config.json |
| Claude Desktop | none | claude_desktop_config.json |
VS Code adds two more surfaces on top: an MCP: Add Server flow that asks whether the
target is Workspace or Global, servers installed into the user profile from the Extensions view, and
customizations.vscode.mcp.servers inside a dev container definition, which VS Code writes
into the container's configuration when the container is created. Sessions running on Agent Host do not
read .vscode/mcp.json directly; VS Code forwards the configuration to it, except servers
that need interactive input.
claude mcp get <name>It shows the definition Claude Code resolved and runs a health check against it. If the entry that comes back is not the one you edited, you edited a lower-precedence copy, and no amount of editing that file will change anything.
This page was written while packaging 30 MCP servers for six clients; the per-client scope facts and
their source URLs are recorded in billing/src/setup.js, read from each vendor's own
documentation on 2026-09-08.
Because the safe default for a command that launches a program is the narrowest one. It costs a flag to widen and costs nothing to be wrong, whereas a user-scope default would put every experiment into every project you open.
No. Project-scoped servers from .mcp.json wait for approval, and since v2.1.196 the approval is not read from files inside the repository until you have trusted the workspace yourself.
No. The documentation is explicit that the entire entry from the highest-precedence source is used. A user-scope entry with an env block and a project-scope entry without one does not produce a merged entry; one of them is used whole.
They can, and they match differently. Named scopes deduplicate by name, while plugins and connectors deduplicate by endpoint, so a connector pointing at the same URL as your server is treated as the same server even if you called it something else.
All MCP servers and prices · All guides · Buy the bundle $39