D3 · Claude Code › Cluster 8 · Automation, MCP & Integrations

8.2 · Adding MCP Servers

claude mcp add · scopes

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:

TransportCommand shapeUse 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.
stdioclaude mcp add <name> -- <command> [args]Local processes / CLIs. The -- separates Claude's flags from the server command.
For stdio servers the -- (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.
🔑 Auth: pass a static token with --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:

ScopeLoads inShared with team?Stored in
local (default)Current project only🔴 No — private to you~/.claude.json (under project path)
projectCurrent project only🟢 Yes — via version control.mcp.json in project root
userAll 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).
Older versions used different names: the current 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

flowchart TD START["claude mcp add"] --> T{"Where does
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

Trap: "Project scope means it lives in ~/.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.
Trap: "You can drop the -- 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 --.
Trap: "SSE is the default remote transport." → HTTP is recommended; SSE is deprecated. Default scope is local, and the default transport when you use -- command is stdio.
Trap: "Adding a project server via CLI auto-enables it for the team." → Teammates still get an approval prompt before a .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).