How do I add, remove, and debug MCP servers from the command line?

The claude mcp command is the primary way to configure MCP servers outside of manually editing JSON files. It manages three scopes, three transport types, and writes to the right config file for each.

Add a remote HTTP server

HTTP is the recommended transport for cloud services:

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

With a Bearer token:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Add a local stdio server

Stdio servers run as local processes. The -- separator is required:

claude mcp add --transport stdio --env AIRTABLE_API_KEY=your-key airtable \
  -- npx -y airtable-mcp-server

Option ordering is strict. All flags (--transport, --env, --scope, --header) must come before the server name. The -- then separates the server name from the command and its arguments. This is the most common source of silent failures.

Correct:

claude mcp add --transport stdio --env KEY=val myserver -- python server.py --port 8080

Wrong (env is silently ignored):

claude mcp add --transport stdio myserver --env KEY=val -- python server.py

Control scope

# local (default): current project only, stored in ~/.claude/settings.json under a project key
claude mcp add --scope local --transport http github https://mcp.github.com/mcp

# project: shared with team via .mcp.json at repo root
claude mcp add --scope project --transport http github https://mcp.github.com/mcp

# user: available across all your projects
claude mcp add --scope user --transport http github https://mcp.github.com/mcp

Project-scoped servers in .mcp.json require a one-time approval from Claude Code before they start. If you dismissed the approval prompt, the server stays disabled. Run /mcp to see status and approve.

Manage servers

# List all configured servers
claude mcp list

# Get details for one server
claude mcp get github

# Remove a server
claude mcp remove github

Inside a session, run /mcp to see connected servers, their tool count, and approval status.

Tune limits

# Set startup timeout (milliseconds)
MCP_TIMEOUT=10000 claude

# Raise per-tool output limit (default is 10,000 tokens, warning shown above threshold)
MAX_MCP_OUTPUT_TOKENS=50000 claude

Debug a server

For stdio servers that fail to start or behave unexpectedly:

claude --debug mcp

This captures the server’s stderr output and logs it to the debug output. Use this before concluding the server itself is broken. Many “broken” servers just have a startup error they print to stderr that never surfaces otherwise.

Footguns

mcpServers in settings.json is ignored. This is the most common MCP misconfiguration. settings.json does not read an mcpServers key. Project-scoped servers go in .mcp.json at the repository root. User-scoped servers go through claude mcp add --scope user. Adding mcpServers to settings.json produces no error and no server.

Project-scoped servers need approval. A server correctly defined in .mcp.json will silently not appear in sessions until approved. Run /mcp after adding a project-scoped server for the first time, or after a teammate adds one, to trigger the approval.

Relative paths in command or args break. They resolve against the directory you launched Claude Code from, not the .mcp.json location. Use absolute paths for local scripts. Executables on your PATH like npx or uvx are fine as-is.

Stdio servers do not reconnect after disconnect. HTTP and SSE servers reconnect with exponential backoff (up to 5 attempts, 1-second initial delay, doubling each time). If a stdio server crashes mid-session, you need to restart the session.

The server name workspace is reserved for internal use. Defining a server named workspace in any config causes Claude Code to skip it at load time with a warning. Pick any other name.

Environment variables in settings.json env do not propagate to MCP child processes. Set per-server env inside .mcp.json instead.

When NOT to use the CLI

Plugin-bundled MCP servers are managed through plugin install and uninstall, not claude mcp. Running claude mcp remove has no effect on a server that comes from a plugin. To remove it, uninstall the plugin.

For organization-wide distribution, server configuration belongs in managed settings or a shared .mcp.json in a shared repository, not in individual claude mcp add calls that each developer has to run.