Claude Code MCP project scope: share a server with your team

In Claude Code, project scope saves an MCP server to a .mcp.json file at the repository root, so everyone who clones the repo gets the same server. Add one with claude mcp add --transport http <name> --scope project <url>, commit the file, and each teammate approves the server and signs in with their own account.

The Claude Code facts come from Anthropic's MCP page for Claude Code, read on 2026-09-28. The example server is Sume's hosted MCP endpoint, set up in the MCP quickstart. What goes inside an mcp.json file in general is covered in MCP JSON config.

What are the three MCP scopes in Claude Code?

Local scope is the default, so a plain claude mcp add stays private to you in the current project. Only project scope is meant for version control.

• When one server name is defined in more than one scope, Claude Code uses the highest-precedence definition, in the order local, project, user. Fields are not merged across scopes.
• So a teammate who also has a local sume entry gets that entry, not the committed one.

How do I add a project-scoped MCP server?

Run the add command from the repository root with --scope project. Claude Code creates or updates .mcp.json for you. For Sume's hosted server:

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

# .mcp.json written at the project root
{
  "mcpServers": {
    "sume": {
      "type": "http",
      "url": "https://mcp.sume.com/mcp"
    }
  }
}

What happens when a teammate opens the repo?

Claude Code does not trust a committed .mcp.json on its own. Its docs describe these steps and exceptions:

• In interactive sessions, Claude Code asks for approval before it uses project-scoped servers. Until then the server shows as Pending approval. claude mcp reset-project-choices resets those choices.
• A cloned repository can't approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to .claude/settings.json is ignored in an untrusted folder.
• In claude -p runs, Agent SDK sessions, and cloud sessions, Claude Code can't show the prompt and loads project-scoped servers without asking. A disabledMcpjsonServers entry blocks a server in every permission mode.
• Each person then signs in with claude mcp login sume or /mcp. Claude Code stores OAuth sign-ins per endpoint.

Where do credentials go if the file is committed?

Commit the URL, never a secret. With an OAuth server there is nothing else to commit: each teammate's sign-in is their own.

On Sume, every OAuth consent starts read-only: Read is locked on and the Write toggle is off by default, so each person decides whether their session can run paid tools (OAuth and API keys). The same page says not to store OAuth tokens in CLI config or paste them into prompts.

If a server needs a key, reference it as a variable instead of pasting it; MCP JSON config shows Claude Code's ${VAR} expansion, and each person keeps the key in their own environment. An API-key session sees Sume's full hosted tool set, paid tools included, while an OAuth sign-in starts read-only. Claude Code reads its own credential variables, such as ANTHROPIC_API_KEY, as empty in a remote server's url and headers, so a committed file can't forward them to a server. Sume's Authentication page says to keep keys out of screenshots and support tickets and to rotate one that is exposed.

Is project scope the right way to share Sume?

It suits a team whose members all work in Claude Code and want the same agent tools. Sume basics notes that hosted MCP still works but is not the primary integration path today; for backend integrations, Sume's docs point to the Developer API at api.sume.com, with the key kept on a trusted server.