What the claude mcp command actually configures

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

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 can cause argument-parsing errors.

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. Teammates get the configuration, but still need the required dependencies, credentials and approval. 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.

Context cost. Current Claude Code can defer tool schemas until needed through MCP tool search. Upfront loading still depends on configuration and provider support. Inspect the effective setup and measure task quality before attributing a regression to server count.

Bad descriptions. The model selects a tool by reading its description. A vague description can make the intended task harder to match. Test a representative request before deciding whether the server is useful.

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, inspect availability, permissions and the chosen workflow; an unused tool alone does not identify the cause.

For a first trial, ask for one known issue by ID using a read-only connector. Verify the returned title and update time against the source, then confirm an out-of-scope repository cannot be read with the same credential.