Remove an MCP server from Claude Code, and make it stay gone

The command

# remove from wherever it lives
claude mcp remove github

# target one scope explicitly
claude mcp remove github --scope user
claude mcp remove github -s project
claude mcp remove github -s local

# confirm
claude mcp list

claude mcp remove github -s local
claude mcp remove github -s project
claude mcp remove github -s user
claude mcp logout github        # clear any stored OAuth credential
claude mcp list

Where each scope actually stores it

Knowing the file matters, because a removal you can verify on disk is a removal you can stop arguing with.

# project scope
jq .mcpServers .mcp.json

# user scope
jq '.mcpServers | keys' ~/.claude.json

# local scope, for this project
jq --arg p "$PWD" '.projects[$p].mcpServers | keys' ~/.claude.json

# per-project disable list, written by the /mcp toggle
jq --arg p "$PWD" '.projects[$p].disabledMcpServers' ~/.claude.json

A project-scoped removal rewrites the tracked .mcp.json. That is correct behaviour and it is also a change to everyone's configuration, so commit it with a message that says why rather than leaving it in someone's working tree.

It came back. Which of the five is it?

Plugin-provided servers

You add and remove these by installing or uninstalling the plugin, not with claude mcp commands. You can still switch one off in /mcp, which stops Claude Code connecting without removing the plugin.

/plugin              # manage installed plugins
/reload-plugins      # apply enable or disable changes mid-session

claude.ai connectors

These are account state, so no local removal touches them. Remove the connector at claude.ai/customize/connectors, or switch connectors off in Claude Code entirely.

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Disabling instead of removing

Removal throws away the configuration. Half the time what you actually want is for the server to stop connecting while the config survives, which is a different operation with three different mechanisms depending on where the server came from.

{
  "disabledMcpjsonServers": ["heavy-server", "legacy-db"]
}

# ignore every configured server for this run
claude --strict-mcp-config --mcp-config '{"mcpServers":{}}'

# or load exactly one, and nothing else
claude --strict-mcp-config --mcp-config ./just-this-one.json

That pair is the fastest way to answer "is an MCP server causing this?" without touching a single config file. If the symptom disappears, you have your answer and nothing to undo.

The leftovers

Removing a server does not clean up everything it created. Three things outlive it.

1. OAuth credentials. Stored in your system keychain on macOS or a credentials file elsewhere, and untouched by remove. Clear them with claude mcp logout <name>, or "Clear authentication" in the /mcp menu.
2. Project approval choices. Approvals and rejections of .mcp.json servers persist per project. Reset them with claude mcp reset-project-choices.
3. Permission rules. Any mcp__server__tool entry in your permissions block, and any hook matcher written against it, stays behind and silently matches nothing.

claude mcp remove old-server
claude mcp logout old-server
claude mcp reset-project-choices     # only if it was a .mcp.json server

# stale permission rules referencing it
grep -rn "mcp__old-server" ~/.claude/settings.json .claude/settings.json 2>/dev/null

Headless runs, CI, and subagents

The rules change once nobody is at a keyboard, and this is where a server you thought was removed does the most damage: a claude -p run or an Agent SDK session cannot show the project-approval prompt, so project-scoped servers from .mcp.json load without asking. The interactive safety net is simply absent.

claude -p "review the diff and comment on risks" \
  --strict-mcp-config \
  --mcp-config ./ci-servers.json \
  --setting-sources user

One related gap worth knowing: a removed server's tools do not vanish from a subagent definition. A subagent whose tools list names mcp__old-server__query keeps that entry, matching nothing, which reads as the subagent quietly failing rather than as a stale reference.

Verifying it is really gone

# 1. configured, with a live health check
claude mcp list

# 2. this specific one, in detail
claude mcp get old-server        # should report it is not found

# 3. inside a session: what actually connected, including plugins and connectors
/mcp

Questions people ask

Keep reading