Adding MCP servers to Claude Code

By Sophie Filer · Updated 26 Oct 2026

Claude Code manages MCP servers with one command, claude mcp add. You never have to open a JSON file unless you want to share servers with your team. Here is the short version, then the details that catch people out.

The short version

Local server (runs on your machine)

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

Remote server (a URL)

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

Check it actually starts

claude mcp list

The double dash matters: everything after it is the command Claude Code runs to start the server. claude mcp list starts each server and prints Connected or an error, so run it after every add.

Choosing where the server is saved

Every server has a scope. The default is local: only you, only in the folder you ran the command from.

Scope	How to set it	Saved in	Available to
local	default	~/.claude.json, under this project	You, in this project
project	--scope project	.mcp.json in the project root	Anyone who clones the repo
user	--scope user	~/.claude.json, top level	You, in every project

Project scope writes a .mcp.json file you can commit. Claude Code will not start servers from that file until each person approves them, which is why a fresh clone shows "Pending approval" in claude mcp list. Start claude in the folder and accept the prompt.

Passing API keys

Use -e for environment variables and put it after the server name. If -e comes first, Claude Code reads the name as another variable and fails with "Invalid environment variable format".

claude mcp add firecrawl -e FIRECRAWL_API_KEY=fc-your-key -- npx -y firecrawl-mcp

For remote servers that take a key in a header, use --header:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_TOKEN"

Keys end up in plain text in ~/.claude.json, or in .mcp.json for project scope. Never commit a .mcp.json that contains a real key.

Other commands worth knowing

Command	What it does
claude mcp get <name>	Shows one server: scope, command, arguments, env and status
claude mcp remove <name>	Removes it (add -s <scope> if the name exists in more than one)
claude mcp add-json <name> '<json>'	Adds a server from a JSON block, such as the configs on MCP Shelf
claude mcp add-from-claude-desktop	Copies servers over from Claude Desktop (macOS and WSL)
/mcp (inside a session)	Shows connected servers and handles OAuth sign-in for remote ones

Questions

Where does Claude Code keep MCP servers?

Local and user servers are in ~/.claude.json. Project servers are in .mcp.json at the root of the project.

Can I paste the JSON configs from MCP Shelf into Claude Code?

Yes. Use claude mcp add-json with the server's inner block, for example claude mcp add-json playwright '{"command":"npx","args":["-y","@playwright/mcp@latest"]}'.

Do Claude Code and Claude Desktop share servers?

No, they keep separate lists. claude mcp add-from-claude-desktop copies the Desktop ones across on macOS and WSL.