How to Manage MCP Server Scopes in 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.

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.

# 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

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.

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.