The claude mcp CLI

Everything you can do to an MCP server without opening a config file

The claude mcp family of subcommands handles every aspect of server management from your shell. You add servers, inspect their status, authenticate with OAuth, and remove them — all without touching a configuration file. Knowing every subcommand and its flags saves time and prevents the misconfiguration errors that come from editing JSON by hand.

Adding servers: add, add-json, add-from-claude-desktop

claude mcp add is the primary command. Its flags control transport type, scope, environment variables, and headers:

claude mcp add --transport http --scope project --header "Authorization: Bearer TOKEN" myserver https://mcp.example.com/mcp

Short forms: -t for --transport, -s for --scope, -e for --env, -H for --header. For stdio servers, the -- separator is required to distinguish Claude's flags from the server command:

claude mcp add --env DB_URL=postgres://... --transport stdio db -- npx -y @bytebase/dbhub

claude mcp add-json accepts a complete JSON configuration object — useful when a server's documentation provides a ready-made snippet or when you need fields that the add command's flags do not expose, like WebSocket configuration or OAuth credentials:

claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

claude mcp add-from-claude-desktop reads the Claude Desktop configuration file and presents an interactive picker to import selected servers. Available on macOS and WSL only. If a server with the same name already exists at the target scope, Claude Code appends a numerical suffix (server_1, server_2, and so on).

Inspecting and managing: list, get, remove

claude mcp list shows all configured servers with their current status. Five states appear in the output:

claude mcp get <name> shows the full configuration for one server, including its transport type, URL or command, configured OAuth credentials, and pending/rejected approval status.

claude mcp remove <name> removes a server. If the same name exists at multiple scopes, pass --scope to target the right one:

claude mcp remove github --scope local

Authentication from the shell: login and logout

claude mcp login <name> runs the OAuth flow for a server directly from your terminal, without opening a Claude Code session. This is particularly useful for CI pipelines or team onboarding scripts where you want to pre-authenticate before starting a session:

claude mcp login sentry

To remove stored credentials later, run claude mcp logout <name>. In environments without a browser — SSH sessions, Linux without a display server — the command detects this automatically and prints the authorization URL for you to open on your local machine. Force URL mode even when a browser is available with --no-browser.

The /mcp panel inside sessions

Inside a running Claude Code session, the /mcp command opens an interactive panel. It shows the tool count next to each connected server, flags servers that advertise tools but expose none (usually a missing environment variable), and provides per-server actions: Reconnect, Authenticate, and for claude.ai connectors, a "Show unused connectors" row that collapses connectors you have never signed in to.

claude mcp serve: Claude Code as a server

claude mcp serve starts Claude Code in server mode, exposing its built-in tools — View, Edit, LS, and others — over the stdio MCP protocol. Any MCP-compatible client can then connect to Claude Code as a tool provider. Claude Desktop is the most common use case; add this to claude_desktop_config.json:

{"mcpServers": {"claude-code": {"type": "stdio", "command": "/full/path/to/claude", "args": ["mcp", "serve"]}}}

Find the full path with which claude. Using just "claude" in the command field causes a spawn ENOENT error if Claude is not in the PATH that Claude Desktop uses. The server exposes Claude's tools to the client; the client is responsible for showing tool call confirmation dialogs to the user.

--mcp-config and reset-project-choices

The --mcp-config flag passes an additional MCP configuration file at startup. Servers in this file load alongside your regular configuration. Importantly, servers from --mcp-config are unaffected by disableClaudeAiConnectors — making this flag useful for CI pipelines or per-invocation tool loading where you need a predictable server set regardless of user settings.

The reserved server name workspace is used internally by Claude Code. If your configuration defines a server with that name, Claude Code skips it at load time and shows a warning asking you to rename it.