claude mcp add: Every Form of the Command

The claude mcp add command registers an MCP server with Claude Code from your terminal, so you never hand-edit a config file. The general shape is claude mcp add <name> -- <command> <args> for a local server, or claude mcp add --transport http <name> <url> for a remote one. Everything else — env vars, scopes, headers, JSON import — is a flag on top of those two forms. This piece covers all of them with commands you can paste as-is.

Why use the CLI at all? Because it writes the config to the right file in the right shape, validates it, and works the same across scopes. Roughly 90% of MCP servers run locally over stdio, so the first form below is the one you'll type most. If you'd rather see the config-file route or a different client, the how to add an MCP server guide covers both.

The two commands you actually need

Almost every install is one of two lines. For a local (stdio) server, put the launch command after a -- separator so Claude Code knows where its own flags stop and the server's begin:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/you/projects

That wires up the official Filesystem server with one allowed directory. For a remote server, drop the -- and pass a URL with the transport flag:

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

That's Context7, which injects version-specific library docs into your prompts — a hosted endpoint, nothing to install. Verify either one with claude mcp list, and inspect a single entry with claude mcp get <name>. That's the whole core loop. The flags below just tune it.

Passing environment variables and secrets

Use -e KEY=value (or --env) to hand a server its API keys — repeat the flag for each variable. This is how you pass tokens without pasting them into a checked-in file:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx -- docker run -i --rm ghcr.io/github/github-mcp-server

One rule that trips people up: env flags go before the --, because they're Claude Code's flags, not the server's. Anything after -- is passed verbatim to the child process. The GitHub MCP Server above runs as a local Docker container over stdio and also offers a hosted remote; if you use the remote, authenticate with a --header instead (see below) rather than an env var.

A better pattern for secrets: reference a shell variable so the literal token never lands in your history — -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN. Set the value in your shell profile once and let expansion do the rest.

Scopes: where the server gets written

The --scope (or -s) flag decides who sees the server, and it's the flag people most often get wrong. There are three values, and the default is local:

Scope	Written to	Who it's for
local (default)	Your user settings, this project only	A server just for you, just here
project	.mcp.json in the repo root	The whole team, committed to git
user	Your user settings, all projects	A server you want everywhere

claude mcp add --scope project linter -- npx -y some-linter-mcp

Pick project for anything the team should share — it writes a .mcp.json you commit, and teammates get prompted to approve it on first use. Pick user for servers you want in every repo, like a docs or search server. Leave it at local when you're just trying something out. Never put secrets in a project-scoped config; use shell env vars, since .mcp.json is version-controlled.

Remote servers, headers, and OAuth

For remote servers the URL replaces the command, and auth comes from a --header or a browser OAuth flow rather than env vars. Many official remotes use OAuth: you run the add command with no secret, then trigger the login flow inside Claude Code and approve in the browser.

When a server wants a static token instead, pass it with --header:

claude mcp add --transport http my-api https://api.example.com/mcp --header "Authorization: Bearer $API_TOKEN"

A note on --transport: http (Streamable HTTP) is the current remote transport, sse exists only for older servers and was deprecated in the March 2025 spec, and stdio is the default you never have to type for local servers. If you're unsure which a server speaks, its listing page says so — and the transport explainer has the full decision. When a remote connection fails, it's almost always auth or the wrong transport; the troubleshooting checklist starts there.

Importing an existing config with add-json

When a server's README gives you a ready-made JSON block, claude mcp add-json imports it directly instead of making you translate flags. Pass the server name and the raw config object as a string:

claude mcp add-json weather '{"command":"npx","args":["-y","weather-mcp"],"env":{"API_KEY":"xxxx"}}'

This is the fastest path when a project publishes its mcpServers entry and you don't want to reverse-engineer it into -e and -- flags. It also round-trips cleanly: what you paste is what gets stored. If you're generating configs for several clients at once, the config generator produces the correct block for each, and you can add-json the Claude Code one straight from its output.

What to skip

Don't add servers you won't use in the next hour. Claude Code feeds every tool from every registered server into the model's context, and the practical ceiling is around 40 tools before selection accuracy drops. Each server you add spends part of that budget whether you call it or not.

So resist wiring up ten servers "to have them." Add the two or three you're actually working against, remove the rest with claude mcp remove <name>, and consult the best MCP servers shortlist before spending a slot. A lean, deliberate set beats a full one every time. For the syntax and options specific to this client, the Claude Code client page has the reference.