MCP Commands
The claude mcp command adds, lists, and removes MCP servers from the shell.
Inside a session, the /mcp command shows the state of each server.
For example, claude mcp list prints each server and tells you if it is connected.
Flags pick the scope, the transport, env vars, headers, and OAuth fields. The commands write to ~/.claude.json or .mcp.json, depending on the scope.
Subcommands
Source: Connect Claude Code to Tools via MCP, Control MCP Server Access for Your Organization, and claude mcp --help.
| Command | Status | What It Does | How It Works |
|---|---|---|---|
claude mcp add [options] <name> <command | Documented | Adds a server. | Writes to the scope and prints Added .... Put -- before a stdio command so its flags are not parsed. A reserved name is rejected. |
claude mcp add- | Documented | Adds a server from a JSON string. | Accepts stdio, sse, http, and ws. The JSON is the entry object, not the mcp wrapper. |
claude mcp add- | Documented | Imports servers from Claude Desktop. | macOS and WSL only. You pick interactively. A name with other characters is rejected. A duplicate gets a suffix such as server_. |
claude mcp get <name> | Documented | Shows one server. | Health-checks approved servers and shows Issue: on a failure. An unapproved . server shows Pending approval. A plugin stdio server shows Command: and NAME=[REDACTED]. |
claude mcp list | Documented | Lists servers. | Shows Connected, Needs authentication, Failed to connect, Pending approval, or Disabled for this project. Warnings show here. |
⚠️ claude mcp remove [options] <name> | Documented | Removes a server. | Without -- it removes from the scope where the server exists. It deletes stored OAuth tokens and the client registration of a remote server. |
claude mcp login [options] <name> | Documented | Runs OAuth for a server. | Works for http, sse, and claude.ai connectors. Without a local browser it prints the URL and asks for the redirect URL. |
claude mcp logout <name> | Documented | Clears stored OAuth credentials. | Does not remove the server. |
claude mcp reset- | Documented | Resets approvals. | Clears every approved and rejected . server for this project. |
claude mcp serve [options] | Documented | Runs Claude Code as an MCP server. | Over stdio. It prints nothing at start. It offers the Claude Code tools to the client, and the client must ask you to confirm. |
claude mcp xaa setup | Gated | Sets the IdP connection for XAA. | Options: --, --, --, --. Writes xaa. The secret comes from MCP_. |
claude mcp xaa login | Gated | Caches an IdP id_. | Runs the OIDC browser login. Options: -- and -- (stores a ready JWT). |
Flags
| Flag | Status | What It Does | How It Works | Used By |
|---|---|---|---|---|
- | Documented | Picks the scope. | local (default), user, or project. On remove, the default is the scope where the server exists. | add, add-, add-, remove |
- | Documented | Picks the transport. | stdio (default), sse, or http. ws is not accepted. | add |
- | Documented | Sets env vars of a stdio server. | KEY=value. Put another option between -- and the name. | add |
- | Documented | Sets headers of a remote server. | "Name: | add |
-- | Documented | Sets the OAuth client ID. | Only for http and sse. | add |
-- | Documented | Prompts for the OAuth client secret. | Masked input. MCP_ skips the prompt. Stored in the keychain (macOS) or a credentials file. Set only when you add the server. | add, add- |
-- | Documented | Fixes the OAuth callback port. | For servers with a pre-registered http://. For xaa setup, an integer from 1 to 65535. | add |
-- | Gated | Enables XAA for the server. | Hidden unless the gate is set. Needs xaa setup, --, and --. Without the gate, Claude Code prints --. | add |
-- | Documented | Prints the authorization URL. | For SSH and headless sessions. You paste the redirect URL back. | login |
-, -- | Documented | Debug output, and a verbose override. | None. | serve |
The /mcp Command
| Command | Status | What It Does | How It Works |
|---|---|---|---|
/ | Documented | Opens the MCP panel. | Shows status, tool count, cached state, and Issue:. You can enable, disable, reconnect, authenticate, and clear authentication. |
/ | Documented | Retries every failed server. | The interactive terminal needs 2. or later. |
/ | Documented | Controls a server without the panel. | Claude Code suggests it when no terminal is attached to a background session. |
/ | Documented | Runs an MCP prompt. | See MCP Runtime. |
Example
Add, check, and remove a server
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add-json weather '{"type":"http","url":"https://example.com/mcp"}' --scope user
claude mcp list
claude mcp get sentry
claude mcp remove weather --scope user