How to disable an MCP server in Claude Code

Open /mcp in Claude Code, select the server and toggle it off. Its configuration stays saved. The choice is stored per project, so check the panel in the project where you want the server disabled.

By Miguel Silva · Updated 2026-09-12

Where MCP configuration actually lives

For manually added servers, project scope uses .mcp.json; local and user scope use ~/.claude.json. You can turn these servers off in /mcp regardless of which file defines them. Plugins and managed configurations can supply other servers.

.mcp.json

Project scope, in the repository root, shared through version control. Ordinary interactive sessions ask for approval; headless and cloud sessions can load these servers without prompting.

~/.claude.json

User scope (every project on the machine) and local scope (this project only, not shared). Both live in this one file.

.claude/settings.json

Not where servers are defined, but where you say which of the .mcp.json ones are allowed to load.

Disabling is different from removing

claude mcp list                 # configured servers and their status
claude mcp get <name>           # one server: transport, command, scope, status
claude mcp add <name> ...       # --scope local | user | project
claude mcp add-json <name> ...  # the same, from a JSON string
claude mcp remove <name>        # deletes the entry
claude mcp login <name>         # OAuth for HTTP and SSE servers
claude mcp logout <name>        # clears the stored credentials

Disabling keeps the entry for later. If you want to remove a server instead, save any configuration you may need before deleting it.

Turning one off without deleting it

Start with /mcp: select the server and turn it off. It remains listed as disabled. The choice is saved per project in ~/.claude.json. The disabledMcpServers list covers ordinary servers, including plugin servers; default-off built-ins use enabledMcpServers instead. These are separate from the project-file approval settings below.

{
  "disabledMcpjsonServers": ["playwright", "sentry"]
}

For a terminal session, --strict-mcp-config limits configured servers to those supplied with --mcp-config. It does not change your saved server definitions. If your organization deploys managed-mcp.json, this flag makes Claude Code exit at startup instead. It is not a security sandbox or a way to bypass organization policy.

claude --mcp-config ./only-this.json --strict-mcp-config

claude --strict-mcp-config          # omit configured servers for this run

• A server in ~/.claude.json under user or local scope is not covered by disabledMcpjsonServers: that setting is about .mcp.json servers.
• An unapproved project server waits for approval in an ordinary interactive session. Headless and cloud sessions can load project servers without that prompt; use an explicit disable setting when you need them excluded.
• Before removal, save any needed server definition privately. Removing a remote server also deletes its stored OAuth tokens and client registration; copying configuration does not preserve that sign-in.

Why disabling beats deleting

Context cost depends on tool-search settings. Deferral avoids loading every tool schema upfront; configurations without deferral still load definitions upfront. Disabling a server is useful for controlling access, not a guarantee of a particular token saving.

A server definition can include a launch command, arguments, environment variables, a URL or headers. Turning it off preserves that setup. Removal deletes the definition, and a remote server may need a fresh sign-in when you add it again.

Questions

How do I disable an MCP server in Claude Code without deleting it?

Use the /mcp panel and toggle the server off. This preserves its configuration and records the choice for that project.

Do I need to edit a file to disable a server?

No. Use the /mcp toggle. Older instructions that say manual editing is the only option do not describe the current interface.

Do MCP servers use up my context window even if I never call them?

Not all configurations load every definition upfront. Tool-search deferral changes that cost; check your settings before estimating savings.