MCP Server Scopes and .mcp.json Configuration in Claude Code

1.Three scopes, two files

Every MCP server you add to Claude Code lives in exactly one scope. The scope settles two things at once: which file holds the definition, and who ends up with the server. There are three scopes but only two files. Local scope and user scope both write to ~/.claude.json in your home directory. Project scope writes to .mcp.json at the repository root, and that is the file you commit.

The default is the one to remember. If you run claude mcp add without a --scope flag, the server goes into local scope: it stays private to you and loads only in the project where you ran the command. That makes local scope the right place for a half-built server you are prototyping in one repository. Your teammates never see it, and your other projects don't load it. User scope is also private, but it follows you into every project, so it suits a personal utility you already trust. Project scope is the only one that travels with the code. Anyone who clones the repository gets the server.

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Nothing is broken. Local scope is doing what it is designed to do. The quickstart's fix is to re-add the server from the project you are in now, or to add it with --scope user so it isn't tied to a project. The quickstart gives a second cause of an empty /mcp: editing a configuration file at a path Claude Code never reads. Claude Code reads only ~/.claude.json and <project>/.mcp.json. Similar-looking paths such as ~/.claude/mcp.json are ignored.

Sources1

2.Writing a shared .mcp.json the team can load

Project scope is how a team shares tooling. A server defined once in .mcp.json is available to everyone who clones the repository, and cloud sessions load a committed .mcp.json too. The file holds one mcpServers object, keyed by server name. Each entry is either a remote endpoint or a program that runs on the local machine.

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

For an HTTP server, url is the endpoint Claude Code connects to. For a stdio server, command and args are the program it launches. The type field matters. Claude Code treats an entry with no type as a stdio server, so a remote entry that has a url but no type fails to load. Server names have rules as well. Use only letters, numbers, hyphens and underscores, and avoid the names Claude Code reserves for its built-in servers. An entry that uses a reserved name is skipped at load time with a warning.

An error in one entry doesn't break the whole file. Claude Code skips a malformed entry, loads the rest, and claude mcp list prints a parse warning that names the offending field.

Committing .mcp.json doesn't mean every teammate automatically runs every server in it. A project-scoped server that a user hasn't approved yet shows as Pending approval until they run claude interactively and accept it. Settings can decide this in advance. enableAllProjectMcpServers approves every server in project .mcp.json files, enabledMcpjsonServers approves the servers it names, and a disabledMcpjsonServers entry rejects a server. If none of these is set, Claude Code asks about each server.

{
  "enabledMcpjsonServers": ["memory", "github"]
}

Sources213

3.Keeping credentials out of the committed file

Everyone with access to the repository can read a committed .mcp.json, so a token pasted into it is a leaked token. The fix is environment variable expansion. Where the secret belongs, you write a ${VAR} reference such as ${GITHUB_TOKEN}. You commit the reference, and each person's environment supplies the actual value on the machine that runs Claude Code. Two forms cover the cases you will meet: ${VAR} and ${VAR:-default}. The part worth memorizing is what happens when the variable is missing.

Look at what the unset, no-default case doesn't do. It doesn't skip the server, and it doesn't substitute an empty string. The server still loads, the literal ${VAR} text is passed through, and a warning names the missing variable. The fix is to set the variable or give the reference a :-default. Remote servers are the exception to watch: in their url and headers, some credential variables come through empty without any warning.

The diagnostics are designed so they don't reveal secrets. If the same server name is defined in more than one scope with different endpoints, Claude Code quotes each endpoint as written, with ${VAR} references left unexpanded, so a resolved API key never shows up in the warning. Sign-ins are tracked separately: OAuth sign-ins are stored per endpoint, so each conflicting definition needs its own sign-in. Another check flags hidden leading or trailing whitespace in values such as headers.Authorization, usually a token pasted with a trailing newline, and it names the field without printing its value. Compare all of this with passing a credential when you add the server:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

--env gives the server a literal value. That is acceptable for a private local-scope server. In a file the whole team shares, use a ${VAR} reference instead.

Sources2

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Local scope means the project's .mcp.json file.Why is that wrong?

   Local scope is stored in ~/.claude.json under the entry for the current project. Only you get it, only in that project, and it is the default when you don't pass --scope. The shared file .mcp.json is project scope.

   Covered in Three scopes, two files

2. 2.If a ${VAR} reference points to an unset variable with no default, the server fails to load.Why is that wrong?

   Claude Code warns and names the variable, but it still loads the server and passes the ${VAR} text through unexpanded. The fix is to set the variable or add a :-default fallback.

   Covered in Keeping credentials out of the committed file

3. 3.A remote server entry in .mcp.json only needs a url.Why is that wrong?

   An entry without a type is read as stdio, so a url entry must also say http, sse or ws.

   Covered in Writing a shared .mcp.json the team can load