Add MCP servers to Claude Code, the right way

MCP (Model Context Protocol) servers extend Claude Code with tools — file operations, API calls, custom automation. The CLI makes adding them a single command. This guide covers the full workflow: add, list, remove, and the discipline of keeping your active server count low.

The cost of an enabled MCP server

Every enabled MCP server injects its tool definitions into the model's context at session start. A server with ten tools might add a few hundred tokens of schema overhead before you type a single character. Multiply that by five always-on servers and you're burning real tokens on tools you won't use in most sessions.

The right mental model: treat MCP servers like browser extensions. Fewer active ones means lower baseline cost, faster context, and a model that isn't distracted by tools it doesn't need. Enable when you need them, remove or disable after.

Add a stdio server

Stdio servers run as a local subprocess. Claude Code spawns the process, writes JSON-RPC messages to its stdin, and reads responses from stdout. Most community MCP packages are stdio servers.

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

A concrete example using a local Node script:

claude mcp add my-tools -- node /home/you/mcp/my-tools.mjs

The -- separator is required. Everything after it is the subprocess command. If your command itself takes flags, the separator keeps them from being parsed by claude mcp add.

For npx-based servers (the most common pattern in the MCP ecosystem):

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

Add an HTTP server

HTTP servers expose a single endpoint over the network. Claude Code connects as an HTTP client, posts JSON-RPC requests, and streams responses. Use --transport http:

claude mcp add --transport http <name> <url>

If the server requires authentication, pass the header inline. The header is stored in your Claude Code config for the session:

claude mcp add --transport http my-remote https://api.example.com/mcp \
  --header "Authorization: Bearer pn_live_abc123"

You can pass multiple --header flags if the server expects additional headers. Accept headers are handled automatically by Claude Code.

Scopes: local, project, user

MCP servers are stored in one of three scopes. The default is local(current project only, not committed). Use --scope to be explicit:

# local — .claude/settings.local.json (gitignored, current project only)
claude mcp add --scope local my-tools -- node ./tools.mjs

# project — .claude/settings.json (committed, shared with the team)
claude mcp add --scope project shared-tools -- node ./shared-tools.mjs

# user — ~/.claude/settings.json (all your projects)
claude mcp add --scope user personal-tools -- node ~/tools.mjs

Keep tokens and personal servers in local or user scope. Only put servers in project scope when every developer on the project needs them and the command is safe to commit (no secrets inline).

List active servers

claude mcp list

This prints every registered server with its name, transport, command or URL, and scope. Run it any time you suspect a stale server is inflating your context.

Remove a server

claude mcp remove <name>

Remove permanently unregisters the server from whichever scope it lives in. If you just want to stop it for a session without removing the registration, restart Claude Code without the server active — but removal is cleaner.

A practical workflow

The pattern that scales well:

• Keep zero always-on MCP servers unless you genuinely use them every session.
• Add a server at the start of the task that needs it.
• Remove it when the task is done, or use --scope local so it never spreads to other projects.
• Run claude mcp list periodically and prune anything you haven't used recently.

The exception: a server like promenow-tools that you use specifically to install or update your statusline. Add it, pull the files, remove it. The whole operation takes under a minute. See the Terminal Pro builder for a one-click version of that workflow.

Troubleshooting

Server not found after add

Run claude mcp listto confirm registration succeeded. If the server shows up there but Claude Code doesn't offer its tools, restart the session — MCP servers are connected at startup, not mid-session.

Stdio server crashes immediately

Run the command manually in your shell first. Claude Code inherits your PATH, but if the command depends on a version manager (nvm, fnm, pyenv), the subprocess may not have the managed runtime in scope. Use absolute paths to the interpreter when in doubt.

HTTP server returns 401

Check that the bearer token is correct and that you passed it with --header "Authorization: Bearer <token>" — not as a query parameter. If you already registered the server without the header, remove it and re-add with the flag.