D2 · Tool Design & MCP › Cluster 7 · Building & Consuming MCP Servers

7.4 · MCP in Claude Code / Desktop

Config & scopes

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.

TransportCommand shapeUse for
HTTPclaude mcp add --transport http <name> <url>Remote/cloud servers (recommended)
SSE (deprecated)claude mcp add --transport sse <name> <url>Legacy remote servers
stdioclaude 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:

ScopeLoads inShared with team?Stored in
local (default)Current project onlyNo (private to you)~/.claude.json (under the project path)
projectCurrent project onlyYes — via version control.mcp.json in the project root
userAll your projectsNo (private to you)~/.claude.json
🔑 Precedence when a name is defined in several places: local > project > user > plugin > claude.ai connectors. The whole entry from the winning scope is used — fields are not merged.
⚠️ project-scoped servers from a checked-in .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

flowchart TD ADD["claude mcp add --scope ..."] --> L{"Which scope?"} L -->|"local (default)"| LF["🟢 ~/.claude.json
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
A JSON entry with a 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
Share a server with the team → project. Personal utility across all your repos → user. Anything credential-heavy you don't want in git → local.

EXAM TRAPS

Trap: Forgetting -- 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.
Trap: Confusing MCP "local scope" with local settings. → MCP local scope lives in ~/.claude.json; it's not .claude/settings.local.json. Only project scope uses the checked-in .mcp.json.
Trap: Expecting a checked-in .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.
Trap: Omitting 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).