CONCEPT claude mcp add connects Claude Code to external tools
MCP (Model Context Protocol) is an open standard for AI-to-tool integrations. An MCP server
gives Claude Code access to your databases, issue trackers, monitoring dashboards, and APIs — so Claude can read
and act on those systems directly instead of you pasting data into chat. You register a server with
claude mcp add, choosing a transport (how Claude talks to it) and a
scope (where the config is stored and who sees it).
Three transports, each with its own add shape:
| Transport | Command shape | Use for |
|---|---|---|
http (recommended) | claude mcp add --transport http <name> <url> | Remote/cloud servers. JSON alias is streamable-http. |
sse (deprecated) | claude mcp add --transport sse <name> <url> | Legacy remote servers — prefer HTTP. |
stdio | claude mcp add <name> -- <command> [args] | Local processes / CLIs. The -- separates Claude's flags from the server command. |
-- (double dash) is mandatory: everything
after it is passed to the server untouched. Without it, Claude Code tries to parse the server's own flags (like
--port) as its own options.--header "Authorization: Bearer …" (short form
-H) or env vars with --env KEY=value (-e). Remote servers that use OAuth
are signed in later with /mcp or claude mcp login <name> — covered in 8.3.CONCEPT Three scopes decide who sees the server
The -s / --scope flag controls where the configuration lives. This is the axis the
exam cares about most:
| Scope | Loads in | Shared with team? | Stored in |
|---|---|---|---|
local (default) | Current project only | 🔴 No — private to you | ~/.claude.json (under project path) |
project | Current project only | 🟢 Yes — via version control | .mcp.json in project root |
user | All your projects | 🔴 No — private to you | ~/.claude.json |
project scope is the collaboration scope: .mcp.json is meant to be
checked into git, so every teammate gets the same servers. For security, Claude Code prompts for
approval before using a .mcp.json server (reset choices with
claude mcp reset-project-choices).local scope was called
project, and the current user scope was called global. When the same
server name is defined in several places, precedence is local → project → user → plugin →
claude.ai connector (highest first; entries are not merged).DIAGRAM Picking transport and scope
the server run?"} T -->|"Remote / cloud"| HTTP["--transport http (recommended)
or sse (deprecated)"] T -->|"Local process / CLI"| STDIO["name -- command args
(-- separates flags)"] HTTP --> S{"--scope ?"} STDIO --> S S -->|"local (default)"| L["🔵 Private, this project
~/.claude.json"] S -->|"project"| P["🟢 Team-shared, checked in
.mcp.json"] S -->|"user"| U["🟠 Private, all your projects
~/.claude.json"] classDef info fill:#cfe2ff,stroke:#0d6efd,color:#084298; classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef warn fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class L info; class P ok; class U warn;
CODE Adding servers across transports & scopes
Each transport, a scope example, JSON import, and Claude Desktop import — all verbatim command shapes from the docs.
# Remote HTTP server (default local scope), with a Bearer token header claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \ --header "Authorization: Bearer YOUR_GITHUB_PAT" # Project scope — writes .mcp.json for the whole team (check it in) claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp # User scope — available across all your projects claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic # Local stdio server — note the -- before the command claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server # Add straight from a JSON blob, or import everything from Claude Desktop claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp"}' claude mcp add-from-claude-desktop # macOS / WSL only # Manage them claude mcp list # all configured servers + status claude mcp get github # details for one server claude mcp remove github # delete it
A team-shared .mcp.json supports env-var expansion so secrets stay out of git:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
}
}
}
TRADE-OFFS Project scope vs. user/local scope
✅ Project scope (.mcp.json)
- Everyone on the repo gets the same servers
- Config is versioned and reviewable
- Env-var expansion keeps secrets out of git
- Approval prompt guards against malicious commits
⚠️ Local / user scope (~/.claude.json)
- Private — good for personal creds & experiments
- User scope follows you across all projects
- But: teammates don't inherit it — not shareable
- Not reviewable in code review
EXAM TRAPS
~/.claude.json." → No.
Project scope writes .mcp.json in the repo root (the shareable, version-controlled file).
Local and user scopes both live in ~/.claude.json.-- for a simple stdio server." → For stdio,
-- separates Claude's flags from the server command. Omit it and Claude Code mis-parses the server's
own flags. HTTP/SSE take a URL, not --.local, and the default transport when you use
-- command is stdio..mcp.json server runs. Reset those choices with
claude mcp reset-project-choices.PRACTICE
Q1 · You want your whole team to get a Postgres MCP server automatically. Which scope and file?
Use --scope project. Claude Code writes the server into .mcp.json at the
repo root, which you check into version control so every teammate inherits it (after a one-time approval prompt).
Local and user scopes stay private in ~/.claude.json.
Q2 · Write the command to add a local stdio server run by npx -y airtable-mcp-server with an API key env var.
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server.
The -- is required so npx and its args pass through to the server untouched.
Q3 · The same server name is defined at local, user, and project scope. Which one wins?
Local scope. Precedence is local → project → user → plugin → claude.ai connector, highest first, and the winning entry is used whole (fields are not merged across scopes).