How to Manage MCP Server Scopes in Claude Code

Choose between local, project, and user scope so each MCP server is shared or private exactly as intended.

7 minIntermediate

Visit Claude Code

When you add an MCP server, Claude Code stores it at one of three scopes. Picking the wrong one is a common cause of a server is missing for a teammate or a secret leaking into a committed file. This guide explains each scope and how to move a server between them.

At least one MCP server already added
Claude Code CLI access
Understanding of which servers should be shared

Step 1: Know the three scopes

Local scope is private to you in this one project. Project scope is committed to .mcp.json and shared with everyone who clones the repo. User scope is private to you but available across all of your projects.

Scope	Stored in	Shared with team	Across projects
local	per-project user config	No	No
project	.mcp.json (committed)	Yes	No
user	~/.claude config	No	Yes

Step 2: Add at the right scope from the start

Pass the scope flag when adding. A team-shared docs server belongs in project scope; a personal scratch server belongs in user scope.

terminal

# shared with the repo
claude mcp add docs --scope project -- npx -y some-docs-server

# private, available everywhere
claude mcp add notes --scope user -- npx -y my-notes-server

zsh - my-project

$ claude mcp list

docs (project) connected

notes (user) connected

github (local) connected

claude mcp list shows the scope of each configured server.

Never commit secrets at project scope

Project scope writes to a file in the repo. If a server needs an API key, keep it in an environment variable referenced from .mcp.json rather than pasting the key itself, or use local scope.

Step 3: Move a server to a different scope

There is no rename-in-place for scope. Remove the server and add it back at the scope you want. The commands are quick and reversible.

zsh - my-project

$claude mcp remove github

Removed github

$claude mcp add --transport http --scope user github https://api.githubcopilot.com/mcp/

Added http MCP server github at user scope

Result: each server now lives at the scope that fits, so shared tooling travels with the repo, personal tooling follows you across projects, and nothing sensitive ends up committed.