Share MCP servers with your team, safely

The steps

One step at a time. When a step’s check matches, tick it and the next one opens.

1. 01

   Step 1 of 4: Pick a scope

   The scope decides who gets a server and where it is stored.

   Local (the default)

   • You, in this project only
   • Stored in ~/.claude.json
   • For servers that carry your own credentials

   Project

   • Everyone who clones the repo
   • Stored in .mcp.json at the project root
   • Committed with the code

   User

   • You, in every project
   • Stored in ~/.claude.json

   Check it worked

   Run claude mcp get claude-code-docs. It names the server’s scope: local, from Day 16.

   It worked — next step Not yet
2. 02

   Step 2 of 4: Move the server to project scope

   A scope is fixed when you add a server, so remove it, then add it again.

   TerminalCopy

   Run: $ claude mcp remove claude-code-docs --scope local

   Run: $ claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

   – What happens: The second command writes .mcp.json in the project root.

   Run: $ git add .mcp.json

   Run: $ git commit -m "Share the docs MCP server"

   .mcp.json · JSONCopy

   {
     "mcpServers": {
       "claude-code-docs": {
         "type": "http",
         "url": "https://code.claude.com/docs/mcp"
       }
     }
   }
   

   Check it worked

   .mcp.json at the project root matches the file above, and git shows it committed.

   It worked — next step Not yet Back
3. 03

   Step 3 of 4: See what a teammate sees

   A cloned repo can’t switch on its own servers; each person approves them once.

   In order:

   1. You

      A teammate runs claude in the repo

   2. File

      Claude Code reads .mcp.json

   3. Claude

      It asks them to approve the server

      Until then the status is ⏸ Pending approval.

   • If they approve

     The server connects for them

   • If they reject it

     Their `.claude/settings.local.json` records the rejection

   Check it worked

   Run claude mcp reset-project-choices, then start claude. The approval prompt for claude-code-docs appears.

   If it didn’t work

   A teammate’s server stays at `⏸ Pending approval`.

   They need to start claude in the repo and accept the prompt. claude mcp list alone never approves a server.

   It worked — next step Not yet Back
4. 04

   Step 4 of 4: Keep tokens out and sign in from /mcp

   Commit where a server lives, never the credential that opens it.

   .mcp.json

   mcpServers.sentry.type: "http"

   Without it, Claude Code skips the server.

   mcpServers.sentry.url: "https://mcp.sentry.dev/mcp"

   An OAuth server needs only type and url; each person signs in.

   mcpServers.<name>.headers.Authorization: "Bearer ${API_KEY}"

   For a token server, reference a variable each person sets, never the token itself.

   Check it worked

   Optional, with a Sentry account: run claude mcp add --transport http sentry https://mcp.sentry.dev/mcp, then in /mcp choose it, Authenticate and sign in. It shows as connected.

   It worked — finish Not yet Back