Claude Code Remove MCP Server: List, Disable, Delete
By Neo Zino - builder of ClockedCode11 min readFind which scope an MCP server lives in, then remove it with claude mcp remove, disable it per project, or fix the ones that refuse to go.
On this page
TL;DR: To do a Claude Code remove MCP server job properly, run
claude mcp get <name>first to see which scope the server sits in, thenclaude mcp remove <name> -s <scope>. The one exception is a claude.ai connector, which the CLI refuses to remove because it treats that scope as read-only (github.com).
| Situation | Command or action | What it does |
|---|---|---|
Server added with claude mcp add (local or user scope) | claude mcp remove <name> -s <scope> | Deletes the entry, and the stored OAuth tokens for a remote server (atlascloud.ai) |
Server defined in a project's .mcp.json | Delete its entry from the file, then check approval status | Removes it for everyone who shares the repo through version control (atlascloud.ai) |
| claude.ai connector (Linear, Notion, Atlassian and so on) | Nothing from the CLI | claude mcp remove fails with a scope error because the claudeai scope is read-only (github.com) |
| Server only a subagent needs | Deny it in .claude/settings.json, grant it in the subagent's frontmatter | Blocks the main session from calling it, but its tool definitions still take up context (github.com) |
How do you see which MCP servers Claude Code has loaded?
Prerequisite: Claude Code installed, and a terminal opened in the project folder you want to clean up. Local-scope servers are stored per project path, so the folder matters (atlascloud.ai).
- Run
claude mcp list. Expected result: one line per server with a connection status. Servers added from a.mcp.jsonfile that you have not approved yet show asPending approval(atlascloud.ai). - Run
claude mcp get <name>for any server you plan to change. Expected result: the scope, the transport and, on the last line, the exact remove command with the scope already filled in (atlascloud.ai). - If a server shows as failed instead of connected, run
claude --debugand read what it prints. The Claude Code maintainers suggest this first when a server will not connect (github.com). - If a pending server is one you do not want, do not approve it. Run
claudein that folder only after you have decided what to do with the entry.
Copy the remove command from step 2 rather than typing your own. It saves you from guessing the scope, which is where most failed removals come from.
If the list itself is the problem, see Claude Code MCP Server Not Working for connection failures.
Which scope is the server in, and where is it stored?
Every server lives in one of three scopes, and the scope decides which file holds it, who can see it, and which delete command reaches it.
| Scope | How it is set | Visible to | File | Goes to teammates via git |
|---|---|---|---|---|
| Local (the default) | --scope local or no flag | You, in this project only | ~/.claude.json, filed under the project's path | No |
| Project | --scope project | Everyone who clones the repo | .mcp.json at the repo root | Yes |
| User | --scope user | You, in every project | ~/.claude.json | No |
Three consequences matter before you delete anything.
- One name in several scopes: Claude Code picks a single definition and does not merge fields. Local beats project, and project beats user (atlascloud.ai). Remove the winning entry and a lower-priority one with the same name can quietly take over.
- Local and user entries sit in the same file. When a server seems to have vanished, the usual cause is that you added it locally while in a different folder.
- Claude Desktop is a separate client. Claude Code reads
~/.claude.jsonand.mcp.json, while Claude Desktop readsclaude_desktop_config.json, so adding a server in one does nothing for the other.
For more on picking a scope at the moment you add a server, see How to Add MCP Servers to Claude Code.
How do you remove an MCP server for good?
Prerequisite: run claude mcp get <name> so you know which scope the entry sits in. The final line of its output is the exact remove command for that entry, scope included (atlascloud.ai). Skipping this is how people delete the wrong copy.
- Run the command it printed, or assemble it from the name and scope, for example
claude mcp remove atlascloud -s user. Expected result: a message confirming the server was removed from that scope. - Pass
-swhenever the same name exists in more than one scope. Without it you cannot be certain which entry gets deleted. - Run
claude mcp listagain. Expected result: the server no longer appears. If a same-named entry shows up now, it is a lower-priority definition from another scope that was hidden before. Remove it as well if you want the name gone completely. - For a remote server, expect to sign in again if you ever re-add it, since removal also clears the OAuth tokens Claude Code stored for it.
Our sources describe no remove command specific to project scope, so open .mcp.json and delete the entry by hand. Commit the change if teammates share the file, otherwise they keep the server. A newly added .mcp.json entry also sits at Pending approval until someone runs claude in that folder and approves it.
Which removal path fits your server: delete, deny, or leave it?
We'd pick the path from where the server came from, not from how annoying it is.
| If the server is... | Then | Because |
|---|---|---|
| In local or user scope and you never use it | Delete with claude mcp remove <name> -s <scope> | It is your own config, so nobody else is affected (atlascloud.ai) |
In .mcp.json and the team uses it | Leave it, or deny it only in your own settings | Deleting the entry changes it for everyone who shares the repo (atlascloud.ai) |
In .mcp.json and nobody uses it | Delete the entry and commit | It is shared config, so the fix is shared too |
| A claude.ai connector | Leave it | The CLI treats the claudeai scope as read-only (github.com) |
| Needed by one subagent only | Deny in main settings, grant in the subagent | The main session stops calling it, but see the caveat below (github.com) |
| Present under the same name in two scopes | Delete the higher-priority copy only if you want the other to take over | Local beats project, and project beats user (atlascloud.ai) |
When this is the wrong choice: denying a server is not a way to save context. A commenter on the Claude Code feature request for per-subagent MCP tools reported that denying a tool in main settings still leaves its MCP tool context occupying space (github.com). If context is why you are here, deny rules will not help. For a server you own in local or user scope, deleting is the fix. For a claude.ai connector you cannot delete from the CLI, expect it to keep appearing as a deferred tool in every session, as the maintainers' issue tracker describes (github.com). Our guide Stop MCP Servers Eating Claude Code Context covers the context side in more depth.
How do you turn a server off without deleting it?
Use this when a subagent needs the server and the main session does not. It is a workaround, not a feature. The request for per-agent MCP loading is still an open issue, because today MCP tools are either fully connected or fully disconnected for the whole session (github.com).
Prerequisite: the server is already configured, and you know its name in claude mcp list.
- Keep the server in
.mcp.jsonso Claude knows it exists (github.com). - In the project's
.claude/settings.json, add a rule underpermissions.denyusing the server'smcp__name. The issue's example denies the Playwright MCP server's tools this way (github.com). Expected result: the main session is blocked from calling that server's tools. - In the subagent file that needs the server, list the tool in the
toolsline of its YAML frontmatter (github.com). Expected result: only that subagent can use it. - Check the subagent's
toolsfield carefully. If it is omitted, the subagent inherits all tools from the main thread. A comma-separated list gives granular control (github.com).
The caveat is real: by default sub-agents inherit every available MCP tool whether they need it or not, and project-level .mcp.json tools are available across the entire session, which adds context overhead (github.com). Step 2 changes what can be called. It does not change what is loaded.
What can you do about claude.ai connectors that will not remove?
Running claude mcp remove "claude.ai Linear" fails with Cannot remove MCP server from scope: claudeai (github.com). That is by design. These connectors are fetched server-side and synced into the claudeai scope, which the CLI treats as read-only.
The desktop app does not help either. Its Connectors panel shows only a Connect button for integrations you have not connected, with no remove, hide or dismiss option (github.com). The built-in ones named in the issue are Asana, Atlassian, Box, Canva, HubSpot, Intercom, Krisp, Linear, Microsoft 365, Miro, monday.com and Notion.
The cost is that unconnected connectors still appear as deferred tools in every session, adding noise to the system context (github.com). The realistic options:
- Accept them. They are unconnected, so they cannot act, and the noise is the only price.
- Use a permission deny rule if you want to be certain a connector is never called. That blocks use, but per the caveat above it does not free context (github.com).
- Watch the upstream issue. The request to remove or hide them is open, and a fix would have to come from Anthropic, not from your config (github.com).
Why did the server come back, or never leave?
Check these in order.
- Wrong scope. You deleted one copy while another scope still holds the same name. Run
claude mcp get <name>and read the scope it reports. - Wrong folder. A local server is tied to one project's path, so opening another folder makes it look gone.
- The project file restores it. A
.mcp.jsona teammate committed brings the entry back on your next pull. Delete the entry in the file and commit. - Still pending. An unapproved
.mcp.jsonentry is listed asPending approvaluntil you runclaudein that folder and approve it (atlascloud.ai). - It is a connector. A name starting with
claude.aiis synced into the claudeai scope, which the CLI treats as read-only and refuses to remove (github.com). - Different client. You edited Claude Desktop's config rather than Claude Code's.
- Still stuck. Run
claude --debugand read what it prints. The Claude Code maintainers ask for this first when a server misbehaves (github.com).
How much context does removing a server actually save?
Every connected server adds its tool definitions to the session, and that overhead applies to the whole session, not just the moments you use the server (github.com). Denying tools does not give that space back, and unconnected claude.ai connectors add deferred-tool noise you cannot delete from the CLI (github.com).
So the ranking is simple. Deleting a server you do not use saves the most. Denying it saves nothing, though it prevents accidental calls. Leaving a connector alone costs only the noise. The facts we have give no per-server token figure, so measure your own setup instead of guessing.
Next action: run claude mcp list now, then claude mcp get on the two servers you use least, and remove them with the scope the output prints. For a method to measure the cost and pick which to cut, read Stop MCP Servers Eating Claude Code Context. To rebuild a lean set afterward, the Claude Code MCP Config Generator writes the config for only the servers you pick.