What the claude mcp command actually configures

MCP is a standard way to hand tools and data to a model. The claude mcp command family is how you register those servers with Claude Code. The whole surface is small:

• claude mcp add <name> -- <command and args> registers a server that runs as a local process.
• claude mcp add --transport http <name> <url> registers a remote server instead.
• claude mcp list shows what is registered and whether it connects.
• claude mcp get <name> shows the full configuration for one server.
• claude mcp remove <name> takes it out again.

Note the bare -- in the add form. Everything after it is the command line for the server process. Leave it out and the flags meant for the server get eaten by the CLI, which is the single most common first-attempt failure.

Scope is the real decision

Every registration lands in one of three scopes, chosen with --scope.

Local is the default. It applies to you, in this project, and nobody else sees it. Fine for experiments and anything holding a personal token.

Project scope writes a .mcp.json file at the repo root, which you commit. Everyone who checks out the repo gets the server. This is the scope you want for anything that is part of how the team works, and the one people forget exists. Because the file is committed, it must not contain secrets. Reference environment variables and let each person supply their own.

User scope registers the server for you across every project. Good for general-purpose things like a docs lookup. Bad for anything repo-specific, because it will load in projects where it is irrelevant and quietly consume context.

What goes wrong after it connects

A connected server is not a useful server. Three problems dominate.

Tool bloat. Every tool's name, description, and parameter schema is sent with requests. A handful of large servers can add thousands of tokens before you have said anything. The symptom is that ordinary editing gets worse right after you added tools meant to make it better. Register fewer servers, and prefer servers that expose a focused set.

Bad descriptions. The model selects a tool by reading its description. If the description is a noun phrase, it will not get called. This is the server author's fault, and it is a fair reason to reject a server.

Unscoped write access. Anything that can change state will eventually be asked to change state during a task that went sideways. Prefer read-only servers, and where you need writes, keep approval manual rather than allow-listing the tool.

Verifying it works

Run claude mcp list and look for a connected status. Inside a session, /mcp shows the servers and lets you authenticate the ones using OAuth. Then run a task that should need the tool and check that it was called. If the model answered without calling it, either the description is wrong or the tool was not needed, and both are worth knowing.

What to do next

Look at what your team registered locally over the past month. Anything that more than two people added independently belongs in project scope, committed, with the token pulled from the environment. That one migration is usually the difference between a few enthusiasts and a team practice.

If you want help putting this into practice, talk to us.