Add an MCP server to Claude Code
The add command, the three scopes, what .mcp.json looks like, and how to keep an extra tool from becoming an extra risk.
An MCP server gives Claude Code extra tools: a database client, an issue tracker, a browser, a docs search. Adding one takes a single command, but three choices decide whether it stays tidy and safe: the transport, the scope, and what the server is allowed to do. This guide uses the options of claude mcp add as printed by claude mcp add --help in the installed version.
Add a server
There are two kinds. A remote server is reached over HTTP:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
A local server is a program that Claude Code starts itself (stdio, the default transport). Put -- before the command so its own flags are not read as Claude Code flags, and pass secrets with -e:
claude mcp add my-server -e API_KEY=xxx -- node ./my-server.js
Remote servers that need a header use --header (or -H), repeated once per header. Servers that use OAuth need a login after adding: claude mcp login <name>. The older sse transport still exists, but HTTP is the one to pick when the server offers both.
Pick a scope
--scope (or -s) takes local, user or project. The default is local.
- local: only you, only in this project. Use it for anything with a personal token.
- user: only you, in every project. Good for a general docs search.
- project: written to a
.mcp.jsonfile in the project root, so it can be committed and shared with the team.
Adding a server with --scope project produces a file like this:
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "node",
"args": ["./my-server.js"],
"env": { "API_KEY": "xxx" }
}
}
}
Do not commit real keys in that file. Keep the secret in your environment and reference it, or add the server in local scope instead.
A server that comes from a .mcp.json is not started blindly. claude mcp list shows it as pending approval until you open claude in that directory and approve it. That is deliberate: a repository you just cloned cannot run programs on your machine without you saying yes.
Check and manage
claude mcp list # all servers, with a health check
claude mcp get my-server # details of one server
claude mcp remove my-server
Inside a session, /mcp shows the same state and lets you handle logins. A server marked as needing authentication is configured but unusable until you run its login.
Control what a server can do
Every MCP tool appears to Claude as mcp__<server>__<tool>, and the normal permission system applies to it: you get a prompt the first time, and an allow or deny rule can name the tool. A local server is an ordinary program running with your user's rights, so treat installing one like installing any other software: read what it does, prefer a pinned version, and give a database server a read-only account.
For a scripted run, --mcp-config loads servers from a JSON file and --strict-mcp-config makes Claude Code use only those, ignoring every other configuration. That keeps an unattended claude -p job from picking up servers you added for interactive work.
Troubleshooting
- Pending approval: open
claudein the project and approve the server.claude mcp reset-project-choicesclears earlier approve or reject choices. - Needs authentication: run
claude mcp login <name>. - Flags of a local server swallowed: the
--is missing between the server name and its command. - Server missing in a new project: it was added in
localscope for another directory. Add it again with--scope user.