Claude Code MCP Setup: Commands, Config Scopes & Servers

Claude Code MCP setup takes about two minutes and permanently changes what the tool can do: MCP servers give Claude Code tools beyond its built-in set — searching your issue tracker, querying a database, driving a browser, reading your analytics. Servers run either locally as subprocesses or remotely as hosted services, and Claude discovers their tools automatically once connected.

This guide covers the CLI flow end to end. If you’re setting up the Claude Desktop chat app instead, that’s a different config file and a different walkthrough — see connecting Claude Desktop. For which servers are actually worth connecting once setup works, we keep a ranked list at best MCP servers for Claude Code.

Everything starts with claude mcp add, run in your terminal (not inside a Claude session). There are two shapes — one for hosted (remote) servers you reach over a URL, one for local stdio servers Claude Code launches as a subprocess:

# Hosted server over Streamable HTTP (the Claude Code docs server —
# a good no-auth first test)
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

# Local stdio server — everything after the -- separator is the
# command Claude Code runs to start it
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Server that authenticates with a static token
claude mcp add --transport http acme https://mcp.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Then verify:
claude mcp list

The parts: the name (claude-code-docs, playwright) is yours to choose — it labels the server’s tools in Claude’s output. The --transport http flag means “hosted at a URL”; omitting it means stdio, where the command after -- is what gets launched. Environment variables a local server needs go in with --env KEY=value.

claude mcp list shows each server with a status: a check for connected, “needs authentication” for servers awaiting a sign-in, and failure states covered in the troubleshooting section. A first stdio run can show as failed while npx downloads the package — wait a moment and list again.

That generator lives at /tools/mcp-config-generator, and it also emits config for Claude Desktop, Cursor and other clients from the same input.

Where claude mcp add writes the server determines who can use it. This is the piece most people learn by being confused — a server added in one project silently absent from another:

Pass --scope user or --scope project to override the default. A server’s scope is fixed at add time — moving it means claude mcp remove then re-adding at the new scope. When the same name exists at multiple scopes, local wins over project, which wins over user.

Project scope is the one worth writing by hand, because .mcp.json is checked into the repository and doubles as configuration-as-code. The format is the same JSON shape all three scopes use:

{
  "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 take a url; stdio servers take a command and args (plus an optional env object). Claude Code reads the file at session start, so restart after editing.

The first time Claude Code sees a project-scoped server it asks each user to approve it. That prompt is a real security boundary — it’s what stops a cloned repository from launching arbitrary processes on your machine without consent. If you rejected one and changed your mind, claude mcp reset-project-choices clears the decision.

Hosted servers from services like Sentry, Linear and Notion sit behind OAuth. The flow is two steps: add the server’s URL as normal, then authenticate from inside a session:

Servers that use a static token instead of OAuth take it at add time via --header "Authorization: Bearer <token>" — which is exactly how you’d connect a hosted business endpoint like a BusinessMCP workspace, where the key’s scope controls which tools the session can even see.

Most failures fall into a handful of buckets. Work down this list:

1. 1“No MCP servers configured” — you added the server in a different project (local scope is per-project), or edited a file Claude Code doesn’t read. The only config files are ~/.claude.json and <project>/.mcp.json.
2. 2Failed to connect (HTTP) — run claude mcp get <name> for the error detail, then curl -I the URL. A 404/405 means the server is up (many MCP endpoints only answer POST); a 401/403 means authenticate; nothing at all means the URL or your network.
3. 3Failed to connect (stdio) — run the configured command directly in your terminal. If it errors, the message names what’s missing (Node, a browser, an env var). If it runs fine, you likely omitted the -- separator when adding.
4. 4Connects but no tools — the server started but registered nothing, which usually means a missing API key. Pass it with --env, or in the env field of the JSON entry.
5. 5Timeout at startup — slow first-run downloads. Raise the limit: MCP_TIMEOUT=60000 claude.

Two closing pointers: if you’re choosing between running servers locally versus pointing at hosted ones, the trade-offs are the subject of our remote vs local MCP guide; and Claude Code can import your existing Claude Desktop servers in one shot with claude mcp add-from-claude-desktop on macOS or WSL.