Home · Guides

claude mcp add, in full

claude mcp add <name> [flags] -- <command> [args...]

The -- is load-bearing. It separates Claude Code's own options from the command line that starts the server. Leave it out and --transport or --env belonging to the server gets eaten by the CLI, or the reverse.

claude mcp add zip -- node /Users/you/mcp-servers/servers/zip/dist/index.js

The flag that costs people an hour

--scope defaults to local, which means private to you and to the directory you ran the command in. Run it in ~, then open a project folder, and the tools are simply absent. No error, no warning, nothing in /mcp.

Scope	Written to	Who sees it
`local` (default)	~/.claude.json	You, in that one directory
`project`	.mcp.json at the repo root	Anyone who checks out the repo
`user`	~/.claude.json	You, in every project

If you want a server everywhere, say so:

claude mcp add --scope user invoice -- node /Users/you/mcp-servers/servers/invoice/dist/index.js

The other flags

`--transport`, `-t`	`stdio`, `http` or `sse`. Defaults to stdio.
`--env KEY=value`	One per variable, before the `--`.
`--header`, `-H`	For an HTTP server. Repeatable.
`add-json <name> '<json>'`	Takes a whole config object, which is the fastest way to paste a block out of a README.

Reading it back

claude mcp list          # every server and whether it connected
claude mcp get zip       # one server, with a health check
claude mcp remove zip    # take it out again

Inside a session, /mcp shows what is connected and reconnects one on demand. There is no restart step in Claude Code at all, which is the main practical difference from Claude Desktop.

Adding a remote server with no local process

claude mcp add --transport http invoice https://mcp.zovo.one/mcp/invoice/t/YOUR_TOKEN

Get the token and the ready-made URL for each server from mcp/connect. The free anonymous token allows 600 calls an hour and keeps your data space for 30 days, refreshed for another 30 on every write, which the connect page states on its face. Nothing is installed and no build step is involved.

Questions

Why does claude mcp list show my server but the tools are missing in the session?

list reports the entry, not a successful handshake. `claude mcp get <name>` runs a health check and is the one that tells you whether the process started and answered. If it started and answered but the tools are still absent, you are in a different directory from the one that holds a local-scope entry.

What is the difference between .mcp.json and ~/.claude.json?

.mcp.json at a repository root is project scope, meant to be committed so a team shares the same servers. ~/.claude.json holds both local scope, which is keyed by directory, and user scope, which is not. Project scope is the one to use when the server is part of how the repo is worked on.

Can I edit .mcp.json by hand?

Yes, and the shape is the same mcpServers object Claude Desktop uses, so a block from any README drops straight in. The CLI is just a writer for it. What the CLI adds is the health check on read-back.

How do I set a license key?

--env MCP_LICENSE_KEY=MCPL1.... before the double dash. Leave it unset and the server runs its free tier, which for most of these servers is a real working tier rather than a trial: per-server limits are listed in data/facts.json in the repository and summarised on the free versus Pro guide.

All MCP servers and prices · All guides · Buy the bundle $39