How do you add MCP servers to Claude Code and share them with your team?

Short answer

You add an MCP server to Claude Code with claude mcp add. With --scope project it lands in a .mcp.json file in the repository, so everyone who clones the repo gets the same servers after approving them. Secrets stay out of the file through ${VAR} expansion or per-user OAuth. Admins can fix or filter the servers for the whole organization with managed-mcp.json, managedMcpServers and allow- and denylists.

The three scopes, and which one shares

Every server you add to Claude Code lands in a scope. The scope decides who else gets it.

Scope Loads in Shared with the team Stored in
local (default) This project, for you No ~/.claude.json
project This project, for everyone Yes, through git .mcp.json in the project root
user All your projects No ~/.claude.json

You choose with -s or --scope. Two commands cover most cases:

claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/
claude mcp add --scope project --transport stdio mytool -- npx -y some-mcp-server

The -- separates Claude Code’s options from the command that starts a local server. SSE still works but is marked deprecated; use http for remote servers.

If the same name exists in more than one place, Claude Code takes the whole entry from the highest source, in this order: local, project, user, plugin servers, claude.ai connectors. Fields are not merged.

Sharing servers through the repo, step by step

  1. Add the server with --scope project. Claude Code writes it into .mcp.json.
  2. Keep secrets out of the file. Use ${VAR} or ${VAR:-default} in url, headers, command, args or env. Each developer sets the variable on their own machine. Better still, use a remote server with OAuth, so nobody needs a key at all.
  3. Commit .mcp.json. Colleagues get it on their next pull.
  4. Each person approves. In an interactive session Claude Code asks for approval before using project-scoped servers. Until then claude mcp list shows them as pending. claude mcp reset-project-choices undoes earlier choices.
  5. Each person signs in. For OAuth servers: /mcp in Claude Code, or claude mcp login <name>. Everyone signs in as themselves.

One thing to know: in non-interactive runs (claude -p), Agent SDK sessions and some cloud sessions, project-scoped servers load without asking. A .mcp.json in a repo you run headless is trusted as-is.

Organization-wide control

By default anyone running Claude Code can connect any MCP server. Anthropic’s documentation states plainly that it reviews connectors for its directory but does not security-audit or manage MCP servers. For admins there are several patterns:

Pattern What it does How
Fixed deployment Your fixed set loads, alongside supported managed and host-provided additions managed-mcp.json with your servers
Disable MCP User-configured servers stop loading; managed and host-provided exceptions remain managed-mcp.json with an empty mcpServers map
Provided servers Everyone gets your remote servers and keeps their own managedMcpServers in managed settings
Approved catalog Only listed servers may be added allowedMcpServers plus allowManagedMcpServersOnly: true
Denylist Block known-bad servers deniedMcpServers

managed-mcp.json lives at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux, %ProgramFiles%\ClaudeCode\ on Windows) and is usually pushed with device management. Match servers by serverUrl or serverCommand: Anthropic warns that a serverName entry is not a security control, because anyone can name any server “github”.

Individual rules can also be set per server in permissions. mcp__github__* matches every tool of the github server, and mcp__github__get_* only its get_ tools. Allow rules accept globs only after a literal mcp__<server>__ prefix, so an unanchored mcp__* in an allow rule auto-approves nothing, while a deny rule of mcp__* removes every MCP tool from Claude’s context. Characters such as . or spaces in a server name become _ in the rule, so a server named my.server is written mcp__my_server__*.

The common misunderstanding

“If it is in .mcp.json, the team shares the same AI setup.” The team shares the same connections. It does not share what happens inside them. Each developer’s Claude Code session still starts fresh, with that developer’s CLAUDE.md files and auto memory. What Claude learned from one person’s corrections yesterday does not reach the next person’s session. And .mcp.json only works in Claude Code: the colleague in Cursor or Codex needs the same servers in a different file. See Cursor MCP servers and Codex MCP servers.

What this means for a team

.mcp.json is the right way to give every Claude Code user the same tools: GitHub, your tracker, your docs. Pair it with clear rules on which servers may write, and with OAuth instead of shared keys. For memory and instructions, the separate question is how what one developer teaches Claude reaches the rest; read does Claude Code have memory and Claude Code memory for teams.

Where Bombos fits

Bombos plugs into Claude Code as one more MCP connection, and into Cursor, Codex, Copilot, ChatGPT and your other AI tools the same way, so they all share one memory: team knowledge, rules the AI learned from corrections, and what already sits in repos, documents and mail, with a trail of what each answer rests on. It runs in our cloud or on your own server, and one developer can try it first with their own agents.

Related questions

Where does Claude Code store MCP servers?

Local and user scope are stored in ~/.claude.json. Project scope is stored in .mcp.json in the project root, which you commit to version control.

Why does Claude Code ask for approval of servers in .mcp.json?

For security, Claude Code asks for approval in interactive sessions before using project-scoped servers. Run claude mcp reset-project-choices to reset those choices.

How do I sign in to a remote MCP server in Claude Code?

Run /mcp inside Claude Code and complete the browser login, or claude mcp login <name> from the shell. Claude Code stores and refreshes the tokens.

Can an admin block MCP servers in Claude Code?

Yes. A managed-mcp.json file gives exclusive control over which servers load, and allowedMcpServers and deniedMcpServers in managed settings filter what users add. An empty managed-mcp.json blocks user-configured servers, but managed additions and host-provided servers can still load.

What if an MCP tool returns too much text?

Claude Code warns above 10,000 tokens and limits MCP output to 25,000 tokens by default. You can raise it with MAX_MCP_OUTPUT_TOKENS.

Sources

  1. Connect Claude Code to tools via MCP (Claude Code docs)
  2. Control MCP server access for your organization (Claude Code docs)
  3. Claude Code Docs: Configure permissions
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.