Manage and share MCP servers

Organize servers with scopes and share them with your team

⏱ Est. ~5 min

01 · Read

When you add an MCP server, you pick a scope that decides who can see it and where it's stored.

Local (default) — private, only in the current project. Stored in ~/.claude.json under your project path. Use this for personal dev servers or servers with sensitive credentials.

Project — shared with your team via a .mcp.json at the repo root. Commit it to git, and everyone who clones the repo gets the same servers. Use this for team-standard tools.

User — available across all your projects. Stored in ~/.claude.json. Good for personal tools you use everywhere (like GitHub or a personal database).

Key points

Local (default): private, current project only
Project: shared with the team via .mcp.json in the repo, committed to git
User: personal, available in all your projects
Pick with --scope local|project|user

02 · Code example

The --scope flag controls where the server config is stored.

Local scope (default — just you, this project)

claude mcp add --transport http stripe https://mcp.stripe.com

Project scope (shared with the team via git)

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

User scope (you, all your projects)

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

Local is the default — you don't need --scope local. Project scope creates a .mcp.json file in your repo that teammates pick up when they pull. User scope lives in your home directory config and follows you everywhere.

03 · Code example

When you use --scope project, Claude Code creates a .mcp.json at your repo root. It looks like this — and you can commit it to git.

.mcp.json (commit to the repo)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Notice the ${DATABASE_URL} syntax — environment variables are expanded at runtime, so you can share the config without exposing secrets. Each teammate sets DATABASE_URL in their own environment. The file structure follows the standard format Claude Code reads automatically.

04 · Read

Once servers are set up, you manage them with a few simple commands.

claude mcp list shows all servers. claude mcp get <name> shows details for one server. claude mcp remove <name> removes a server.

Inside Claude Code, type /mcp to see server status, authenticate with OAuth servers, or troubleshoot connection issues. When a server isn't responding, /mcp is the first place to look.

Key points

claude mcp list — see all configured servers
claude mcp get <name> — details for one server
claude mcp remove <name> — remove a server
/mcp inside Claude Code — status, auth, troubleshooting

05 · Quiz

Everyone on your team needs to use the same Sentry MCP server. You want the config committed to git so new teammates get it automatically. Which scope do you use?

Local (default)
Project
User
Global

06 · Drag to sort

You have three different MCP servers to set up. Match each to the right scope based on who needs them.

(This section is interactive — please enable JavaScript.)

Other lessons in this chapter

⚠ The full interactive experience needs JavaScript. Please enable it and reload.

※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.