MCP server scopes and secrets in Claude Code

1.Three scopes, two questions

Every MCP server you add to Claude Code goes into an installation scope. The scope settles two things together: which projects the server loads in, and whether your teammates get it. The exam guide frames this as project-level versus user-level, but Claude Code has a third scope, local, which is the one you get by default. You need all three to answer scoping questions correctly.

Project scope is for shared team tooling. The entry goes into .mcp.json at the repository root, gets committed, and loads for everyone who clones the repo. Pass --scope project and Claude Code writes the file for you:

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

User scope is for personal servers you want in every project, such as a tool you like that the team hasn't adopted. Local scope is for a server that is yours alone and belongs to one repository, such as an unstable prototype you don't want loading anywhere else. Local and user servers are both stored in ~/.claude.json, so knowing which file a server is in doesn't tell you its scope. What matters is the key it sits under: a project entry or the top-level mcpServers.

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Two mistakes come up often. Claude Code reads only ~/.claude.json and <project>/.mcp.json. A file at a path like ~/.claude/mcp.json is silently ignored, and the symptom is that /mcp reports no servers. Also, if you define the same server name with different endpoints in more than one scope, Claude Code warns about the conflict. Keep the definition you want and remove the others with claude mcp remove <name> --scope <scope>.

Sources12

2.Keeping tokens out of a committed .mcp.json

Committing .mcp.json creates a problem: shared servers usually need credentials, and a token written into a committed file is a leaked token. Claude Code handles this with environment variable expansion inside .mcp.json. It supports two forms: ${VAR}, which takes the variable's value, and ${VAR:-default}, which falls back to the default when the variable isn't set. The docs list the fields where expansion applies: command, args, env, url, and headers. That covers both stdio servers (which take credentials through env or args) and remote servers (which take them through headers).

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

The committed file describes the shape of the connection: the endpoint, the header name, and where the token comes from. The token itself never appears. Each developer exports API_KEY in their own shell. If API_BASE_URL is unset, the URL falls back to https://api.example.com. A shared GitHub server works the same way, with "Authorization": "Bearer ${GITHUB_TOKEN}" in place of a literal personal access token.

Compare this with the docs' command-line example, claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT". That command writes a literal token into the configuration. At local scope only your own ~/.claude.json holds it. Copy the same literal into a project-scoped entry and you have committed it.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      " ? ": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Sources2

3.What teammates see when they load your .mcp.json

A committed .mcp.json doesn't connect automatically on a teammate's machine. Until they run claude interactively and approve it, claude mcp list reports the server as ⏸ Pending approval. This is deliberate, because a repository you cloned shouldn't be able to start processes on your machine without your consent.

The next issue is environment variables that aren't set. If a ${VAR} reference names a variable that is unset and has no :-default, Claude Code doesn't refuse the server. It warns in claude mcp list and /mcp, naming the variable, and then loads the server with the literal ${VAR} text in place. The usual result is a server that receives a nonsense argument or header. The fix is to set the variable or add a ${VAR:-default} fallback. Remote servers have one exception: in a url or headers value, some credential variables are read as empty, and no warning is shown.

Claude Code also avoids leaking expanded values in its own output. Warnings and connection errors quote the configuration as written, with ${VAR} references left unexpanded, so a resolved API key never appears in the message. It also warns about leading or trailing whitespace in values such as headers.Authorization, which usually comes from pasting a token with a trailing newline. It names the field without echoing the value, and it doesn't trim the whitespace for you.

For remote HTTP servers that support it, OAuth avoids handling a token yourself. Add the server, then sign in from /mcp in the browser. Claude Code stores and refreshes the tokens. If you configured the Authorization header yourself and the server returns 401 or 403, Claude Code reports a failed connection instead of offering a sign-in, because the credential that needs fixing is the one you supplied.

Sources2

Exam traps

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

1. 1.A personal prototype server that should load in only one repository belongs at user scope, because user scope means 'not shared'.Why is that wrong?

   User scope is unshared, but it loads in all your projects. A server for one repository that only you use belongs at local scope, which is the default.

   Covered in Three scopes, two questions

2. 2.If a ${VAR} in .mcp.json is unset and has no default, Claude Code refuses to load that server.Why is that wrong?

   Claude Code warns, naming the variable, and still loads the server with the ${VAR} text unexpanded. The server then gets the literal placeholder.

   Covered in What teammates see when they load your .mcp.json

3. 3.Once .mcp.json is committed, the server connects automatically for every teammate.Why is that wrong?

   Each user has to approve a project-scoped server interactively. Until then it shows as Pending approval.

   Covered in What teammates see when they load your .mcp.json