Claude Code MCP Server Setup 2026: claude mcp add, Scopes, and .mcp.json

How do you add an MCP server to Claude Code? Run claude mcp add from a terminal, not from inside a claude session. For a hosted server: claude mcp add --transport http <name> <url>. For a local process: claude mcp add <name> -- <command> <args>. Claude Code writes the entry to ~/.claude.json by default (local scope, this project only) unless you pass --scope user or --scope project. Restart isn't required for CLI-added servers, but any hand-edited .mcp.json only takes effect on the next session start.

This is specifically about Claude Code, Anthropic's CLI coding agent — not Claude Desktop, which is a separate app with its own claude_desktop_config.json and its own guide: Claude Desktop MCP Setup. If you followed a Claude Desktop tutorial and it doesn't match what you're seeing in a terminal, that's why.

Quick reference

Prerequisites

Adding a hosted (remote) MCP server

Hosted servers connect over a URL instead of running as a subprocess. Anthropic's own example is the Claude Code documentation server, which needs no auth:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Breaking down the command: claude mcp add registers the server; --transport http tells Claude Code this is a URL-based server rather than a local process; claude-code-docs is a name you choose — it labels the server's tools in Claude's output and is what you'd type in claude mcp remove <name> later; the final argument is the server's URL.

Check the connection:

claude mcp list

You'll see a status next to each server: ✔ Connected means it's ready. ! Needs authentication means the server is reachable but wants a browser sign-in or a token — see the OAuth section below. ✘ Failed to connect or ✘ Connection error means something's actually broken; see Troubleshooting.

Servers that take a static bearer token instead of OAuth accept it at add time:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp --header "Authorization: Bearer <token>"

Adding a local (stdio) MCP server

A stdio server is a program Claude Code spawns as a subprocess — the right choice for anything that needs local resources: a browser, your filesystem, a database socket. No --transport flag is needed since stdio is the default. Everything after -- is the exact command Claude Code runs to start the server:

claude mcp add playwright -- npx -y @playwright/mcp@latest

The -- separator matters. Omit it and Claude Code may try to parse your server's own flags as its own. If a server's first connection attempt shows ✘ Failed to connect, that's often just npx still downloading the package on its first run — check again with claude mcp list after a few seconds before assuming something's wrong.

To confirm a stdio server actually starts, run its command directly in your terminal (outside Claude Code):

npx -y @playwright/mcp@latest

If it starts and hangs waiting for input, the server itself is fine — the problem, if there is one, is in how Claude Code is invoking it. If it errors immediately, the message usually names what's missing (a runtime, a browser, an API key).

Connecting a server that needs OAuth sign-in

Hosted services like Sentry, Linear, and Notion run behind OAuth. Add the server the same way as any hosted server:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp list shows ! Needs authentication — that's expected. Start a session, open the MCP panel, and complete sign-in:

/mcp

Select the server, press Enter, choose Authenticate, and approve the connection in the browser tab that opens. Status flips to connected once you're back in Claude Code.

Scopes: local, project, and user

A server's scope is fixed at add time — changing it means removing the entry and re-adding it at the new scope.

Local (default). Private to you, active only in the project you were in when you ran claude mcp add. Written to ~/.claude.json under that project's entry.

claude mcp add --scope local --transport http claude-code-docs https://code.claude.com/docs/mcp

User. Private to you, active in every project you open. Use this for a server you always want available regardless of which repo you're working in.

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Project. Shared with anyone who clones the repository — written to .mcp.json at the project root, meant to be committed to version control.

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Teammates who pull a repo with a committed .mcp.json get prompted to approve each server the first time they start Claude Code there — the prompt exists so cloning a repo can't silently launch processes on someone else's machine.

If a server is defined at more than one scope simultaneously, claude mcp remove <name> will report "exists in multiple scopes" — pass --scope explicitly to pick which copy to delete.

Editing .mcp.json directly

Every scope's file uses the same JSON shape for server entries. .mcp.json at the project root is the one most worth hand-editing, since it's the file your team reviews and commits:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

HTTP servers need url. Stdio servers need command and args. Claude Code reads .mcp.json at session start — save the file, then start a new session in that project rather than expecting a running session to pick up the change. First-time approval still applies to hand-written entries the same as CLI-added ones.

Passing environment variables and secrets

Pass a variable at add time with --env:

claude mcp add my-database --transport stdio --env DATABASE_URL=postgresql://localhost:5432/mydb -- npx @modelcontextprotocol/server-postgres

Or in a project-scoped .mcp.json, reference an environment variable name rather than hardcoding a secret, so the committed file stays safe while each developer supplies the value locally through their own shell environment. A server that connects but registers zero tools is the classic symptom of a missing required variable — check the server's own docs for what it expects before assuming the MCP config itself is wrong.

Importing servers from Claude Desktop

If you already have servers configured in the separate Claude Desktop app, don't hand-retype them:

claude mcp add-from-claude-desktop

Works on macOS and WSL. It reads Claude Desktop's claude_desktop_config.json and offers to import each entry into Claude Code.

Connecting from other Claude Code surfaces

The CLI isn't the only place to manage MCP servers:

Troubleshooting

/mcp shows "No MCP servers configured." Local-scoped servers are tied to the exact project directory where you ran claude mcp add — the repository root, or the directory itself if it isn't a git repo. If you're in a different project than where you added it, either re-add it here or add it with --scope user so it isn't project-bound. Also confirm you edited one of the two real config paths, ~/.claude.json or <project>/.mcp.json — paths like ~/.claude/mcp.json or ~/.claude/config/mcp.json are not read.

Status is ✘ Failed to connect or ✘ Connection error. Run claude mcp get <name> for the error detail first. For HTTP servers, check reachability directly: curl -I <url> — a 404/405 still confirms the endpoint is up (most MCP endpoints only answer POST); no response at all points at network or firewall. A 401/403 means it's up and wants authentication. For stdio servers, run the exact configured command in your terminal outside Claude Code and read whatever it prints.

Connection times out at startup. The default startup timeout is 30 seconds, and a stdio server's first run can be slow while npx downloads the package. Raise it with MCP_TIMEOUT in milliseconds: MCP_TIMEOUT=60000 claude.

"Server already exists." You already have a server with that name at that scope. Remove the existing one (claude mcp remove <name>, add --scope if it exists at more than one) or pick a different name.

Connects, but zero tools show up. Almost always a missing required environment variable, like an API key the server needs to initialize. Run /mcp, select the server, and check its tool list — empty means it started but couldn't register anything. Pass the missing variable with --env or in .mcp.json's env field.

Edited .mcp.json and nothing changed. Claude Code only reads the file at session start — exit and restart. If servers still don't appear, run /mcp and look for a parse warning; malformed entries are silently skipped rather than crashing the whole file. If you rejected a project server's approval prompt earlier, reset it with claude mcp reset-project-choices.

Frequently Asked Questions

Is Claude Code's MCP setup the same as Claude Desktop's? No. They're separate products with separate config files — Claude Code uses ~/.claude.json / .mcp.json managed via claude mcp add; Claude Desktop uses claude_desktop_config.json, covered in Claude Desktop MCP Setup. claude mcp add-from-claude-desktop bridges the two by importing Desktop's servers into Code.

Do I need to restart Claude Code after adding a server with the CLI? Not for claude mcp add itself — it takes effect for the next session you start. If you're mid-session, start a new one to pick up the change, or hand-edit .mcp.json and restart the same way.

What's the difference between local, project, and user scope? Local (default) is private to you and tied to one project. User is private to you but active everywhere. Project is shared via .mcp.json, meant to be committed so teammates get the same servers after a prompt to approve each one.

Can I run an MCP server over SSE instead of HTTP? Yes — --transport sse is supported alongside --transport http for hosted servers; stdio remains the default for local processes.

Related guides

Official docs cited