The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

claude mcp add is the command most people meet on day one with MCP and get wrong on day one as well: the server name goes in a different place depending on the transport, the -- separator is easy to omit and quietly changes what gets parsed, and --scope defaults to the one value that makes a server vanish the moment you open a different folder. This is a reference for the whole claude mcp command family, written from the current Claude Code documentation, with the syntax for each subcommand, what each scope means and where it is stored, and the half-dozen mistakes that produce most of the questions.

It complements our general MCP servers guide and the post on .mcp.json in subfolders and monorepos; this one is purely about the CLI.

The three shapes of claude mcp add

There is one command with three shapes, chosen by the transport. In every shape the server name is a positional argument that comes before the URL or the command.

# Remote server over HTTP (recommended for remote servers)
claude mcp add --transport http <name> <url>

# Remote server over SSE (deprecated transport, still accepted)
claude mcp add --transport sse <name> <url>

# Local server started as a process (stdio)
claude mcp add [options] <name> -- <command> [args...]

Three real examples, one per shape:

claude mcp add --transport http notion https://mcp.notion.com/mcp

claude mcp add --transport sse asana https://mcp.asana.com/sse

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Since Claude Code v2.1.265, --transport http tries HTTP first and falls back to SSE if the server does not accept it, so for a remote server you can usually just say http. On earlier versions, pick sse explicitly for an SSE-only server.

The -- separator

For stdio servers, everything before -- is read as Claude's own options (--transport, --env, --scope) and everything after it is passed to the server unchanged. Leave it out and a flag meant for the server, such as --port 8080, is parsed as a Claude option and rejected or silently misread.

# runs: npx server
claude mcp add --transport stdio myserver -- npx server

# runs: python server.py --port 8080, with KEY=value in its environment
claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080

One parsing quirk is worth knowing: if the server name directly follows an --env KEY=value pair, the CLI reads the name as another pair and rejects it. Put another option between them, as in the Airtable example above, where --transport stdio sits between --env and the name.

Options reference

• --transport / -t: http, sse or stdio. ws is not accepted here; use add-json for a WebSocket server.
• --scope / -s: local, project or user. Default is local. See the scopes section below, because this is the option that causes the most confusion.
• --env / -e: KEY=value, an environment variable for a stdio server. Repeat it for several.
• --header / -H: an HTTP or SSE header such as "Authorization: Bearer your-token". Repeatable.
• --client-id, --client-secret, --callback-port: for a remote server with a pre-configured OAuth client. --client-secret takes no value on the command line; it prompts with masked input, and in CI reads MCP_CLIENT_SECRET instead.

A successful add prints an Added ... line. If you see was not saved instead, the write to the config file failed; check that the file is writable and, for --scope project, that you are in the directory you think you are in.

Scopes: local, project and user

A scope is where the server definition is stored, which decides where it loads and who else gets it.

• local (the default): stored in ~/.claude.json under projects["<project path>"].mcpServers. Loads only when you start Claude Code in that project path. Not shared with anyone. This is why a server you added yesterday is missing today: you opened a different folder.
• project: stored in .mcp.json at the project root. Loads in that project for everyone who checks the file out, which is the point; commit it. Project servers need a one-time approval in interactive sessions, and approvals from a repository's own settings are ignored until you trust the workspace.
• user: stored in ~/.claude.json as the top-level mcpServers. Loads in all your projects. Not shared. The right scope for a personal tool you want everywhere.

The same server written to each scope:

# local (default): only this project, only you
claude mcp add --transport http stripe https://mcp.stripe.com

# project: this project, everyone, via .mcp.json
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# user: all your projects, only you
claude mcp add --transport http stripe --scope user https://mcp.stripe.com

When the same server name is defined in several places, the highest scope wins and its whole entry is used, with no field merging. The order is local, then project, then user, then plugin-provided servers, then claude.ai connectors. Managed configuration can also provide servers, and from v2.1.259 managedMcpServers ranks above everything. Duplicates are matched by name for the three scopes and by endpoint for plugins and connectors, where two URLs count as the same endpoint if they differ only in scheme, host case, the scheme's default port or a trailing slash.

claude mcp add-json

When you have a JSON block from another client's documentation, or need a transport the plain add does not accept, pass the server definition directly:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

It accepts type values http, stdio, sse and ws, with streamable-http as an alias for http. Two traps: a url entry without a type is a configuration error that Claude Code reads as stdio and skips, and if you copy a block from another client's mcpServers config you must pass only the object inside it, not the wrapper. So {"mcpServers":{"example":{"command":"npx","args":["-y","@example/mcp-server"]}}} becomes claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'. Add --scope user to store it for all projects.

claude mcp add-from-claude-desktop

On macOS and WSL, this opens an interactive picker that imports servers from the Claude Desktop configuration. Names may contain only letters, numbers, hyphens and underscores; servers with other characters are reported and skipped, and a name that already exists gets a numeric suffix such as server_1. Pass --scope user to import into your user configuration.

Listing, inspecting and removing: list, get, remove

claude mcp list                 # every configured server, with health status
claude mcp get notion           # details for one server
claude mcp remove notion        # remove a server
claude mcp remove notion --scope user   # remove from one specific scope
claude mcp login sentry         # run the OAuth flow from the shell
claude mcp login sentry --no-browser    # print the auth URL instead
claude mcp logout sentry        # clear stored credentials
claude mcp reset-project-choices        # reset approvals for .mcp.json servers

• list shows a status per server: Connected, Needs authentication, Failed to connect, Pending approval (run claude to approve), Rejected (see disabledMcpjsonServers in settings), or Disabled for this project (re-enable via /mcp). Since v2.1.219 the failure detail is appended to the line; earlier versions showed only the bare status.
• get prints an Issue: line for a failing server with the HTTP status or error text. Credential-looking text is redacted and the expanded URL is never shown, so a get is safe to paste into a bug report.
• remove also deletes stored OAuth tokens and client registration for a remote server. If the same name exists in more than one scope, pass --scope, or you may remove a different definition than the one that is actually loading.
• login notices when there is no browser (SSH, headless Linux) and prints the URL; paste the full redirect URL back at the prompt, and use ssh -t so the prompt works.

claude mcp serve and /mcp

claude mcp serve runs Claude Code itself as a stdio MCP server for another client such as Claude Desktop. It prints nothing at startup and waits for the client; if the client reports spawn claude ENOENT, use the full path from which claude in its config.

Inside an interactive session, /mcp is the companion to the CLI: it shows each server's status and tool count, authenticates OAuth servers (with Re-authenticate and Clear authentication), turns servers on or off for the current project (stored as disabledMcpServers or enabledMcpServers in ~/.claude.json), and reconnects a server. /mcp reconnect all retries every failed or unauthenticated server, from v2.1.284.

Environment variables in definitions

Definitions in .mcp.json and in local and user entries can reference environment variables with ${VAR} and ${VAR:-default} in command, args, env, url and headers. An unset variable with no default loads as the literal text and triggers a warning in list and /mcp. In a remote server's url and headers, credential variables such as ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN read as empty so that a checked-in project file cannot exfiltrate them; to pass a credential on purpose, copy it into a variable with your own name first.

The six mistakes behind most “claude mcp add” questions

1. Forgetting --scope and losing the server. The default is local, which is tied to the folder you ran the command in. If you want it in every project, add --scope user; if the team should have it, use --scope project.
2. Putting the name after the URL. The name is positional and comes first: claude mcp add --transport http notion https://..., not the other way round.
3. Omitting -- for a stdio server. The server's own flags get parsed as Claude options.
4. Name immediately after --env. The CLI reads it as another pair. Put --transport stdio between them.
5. Pasting an mcpServers wrapper into add-json. Pass only the inner object, and make sure a remote entry has a type.
6. Removing the wrong copy. With the same name in two scopes, remove without --scope may delete the one that was not loading. Run claude mcp get name first; it tells you which scope is in effect.

When a server is added in the right scope and still does not appear, the next place to look is approval: project servers wait for a one-time approval, and in headless or non-interactive runs nobody is there to grant it. The subfolders post covers that case, including --strict-mcp-config and the settings keys that pre-approve servers.