CONCEPT claude mcp add — one command, three transports
Claude Code adds MCP servers with claude mcp add, choosing the transport with
--transport (-t). HTTP is recommended for remote/cloud servers; SSE is deprecated; stdio
runs a local process. For stdio, a -- separates Claude's flags from the server command.
| Transport | Command shape | Use for |
|---|---|---|
| HTTP | claude mcp add --transport http <name> <url> | Remote/cloud servers (recommended) |
| SSE (deprecated) | claude mcp add --transport sse <name> <url> | Legacy remote servers |
| stdio | claude mcp add <name> -- <command> [args] | Local process servers |
Auth headers go via --header (-H), env vars via --env (-e).
Manage servers with claude mcp list, claude mcp get <name>,
claude mcp remove <name>, and /mcp inside a session (which also runs OAuth login —
or claude mcp login <name> from the shell).
CONCEPT Three scopes decide where config lives and who shares it
The --scope (-s) flag controls where the server entry is written and its visibility:
| Scope | Loads in | Shared with team? | Stored in |
|---|---|---|---|
| local (default) | Current project only | No (private to you) | ~/.claude.json (under the project path) |
| project | Current project only | Yes — via version control | .mcp.json in the project root |
| user | All your projects | No (private to you) | ~/.claude.json |
.mcp.json require your
approval before Claude Code will use them (they appear as "⏸ Pending approval") — a guardrail against a cloned repo
silently running someone else's server.DIAGRAM Scope routes the config file and sharing
this project · private"] L -->|"project"| PF["🔵 .mcp.json in repo root
shared · needs approval"] L -->|"user"| UF["🟠 ~/.claude.json
all projects · private"] PF -.->|"teammate clones repo"| APPROVE["⏸ Pending approval
until trusted"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef net fill:#cce5ff,stroke:#4a90d9,color:#0b3d66; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class LF ok; class PF net; class UF gate;
CODE Adding servers and the config file shapes
Real commands across transports and scopes, plus the JSON they produce.
# Remote HTTP, default (local) scope claude mcp add --transport http notion https://mcp.notion.com/mcp # Remote HTTP with a Bearer header claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \ --header "Authorization: Bearer YOUR_GITHUB_PAT" # Local stdio server — note the -- before the command claude mcp add --env AIRTABLE_API_KEY=KEY airtable -- npx -y airtable-mcp-server # Project scope → writes a shareable .mcp.json in the repo root claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
// .mcp.json (project scope, checked into version control) { "mcpServers": { "api-server": { "type": "http", // "streamable-http" is an accepted alias "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } }, "local-tool": { "command": "/path/to/server", "args": [], "env": {} } } }
// Claude Desktop — claude_desktop_config.json (same mcpServers shape) { "mcpServers": { "claude-code": { "type": "stdio", "command": "claude", "args": ["mcp", "serve"], "env": {} } } } // Import existing Desktop servers into Claude Code: // claude mcp add-from-claude-desktop
url but no type is a config error — Claude
Code reads a typeless entry as a stdio server and skips it. Always set "type": "http" (or
"sse"/"ws") on URL entries.TRADE-OFFS Which scope to choose
✅ project scope (.mcp.json)
- Team gets the same servers via version control
- Env-var expansion keeps secrets out of the file
- Approval gate protects against untrusted repos
⚠️ local / user scope
- local: private & per-project — good for experiments and personal credentials
- user: available everywhere for you, but not shared with the team
- Neither is checked in, so teammates don't inherit them
EXAM TRAPS
-- for stdio servers. → Everything after -- is the
server command, untouched. Without it, Claude Code tries to parse the server's own flags (like --port)
as its own options.~/.claude.json; it's not .claude/settings.local.json. Only project scope uses the
checked-in .mcp.json..mcp.json server to "just work" for teammates. →
Project-scoped servers require approval before use ("⏸ Pending approval") — a security guard against running
an untrusted repo's server automatically.type on a URL entry in JSON. → A url with no
type is treated as a stdio server and skipped. Set "type": "http" (or the
streamable-http alias).PRACTICE
Q1 · Name the three MCP scopes in Claude Code and where each is stored.
local (default; current project, private; ~/.claude.json), project
(current project, shared via version control; .mcp.json in the repo root), and user (all your
projects, private; ~/.claude.json).
Q2 · You want your team to inherit a server via git. Which command?
claude mcp add --transport http <name> --scope project <url> — project scope
writes a checked-in .mcp.json. Teammates must still approve the pending server before Claude Code uses
it.
Q3 · How does Claude Desktop configure MCP, and how do you bring those servers into Claude Code?
Claude Desktop uses claude_desktop_config.json with the same mcpServers
object. Run claude mcp add-from-claude-desktop to import those entries into Claude Code (macOS/WSL).