How to Disable a Codex MCP Server Without Deleting It

To temporarily disable one MCP server in Codex, set enabled = false in that server's existing mcp_servers block. Codex will keep the command, URL, environment-variable names, timeouts, and tool filters in config.toml, but it will skip starting the server. Set the value back to true, or remove the line, when you want the server available again.

Do not replace the whole table with mcp_servers = {}. Codex merges CLI configuration overrides, so an empty table can leave every configured server enabled. Also do not run codex mcp remove when your goal is only to pause a working configuration: removal deletes the registration you may need later.

This guide is for a Codex user who wants to isolate slow startup, a broken MCP process, an OAuth problem, or unnecessary tool context without losing the server setup. The job is complete when the named server remains in codex mcp list --json, reports enabled: false, and no longer starts in a fresh Codex session.

Choose pause, restrict, or remove

These controls solve different problems:

If the server is healthy and you only want fewer model-visible tools, restrict its tool list instead of disabling the whole server. If its credentials are suspected to be compromised, disabling startup is not credential revocation. Revoke or rotate the credential at the provider and clear the relevant OAuth session through the supported flow.

1. Record the exact server name

Start with the machine-readable inventory:

codex mcp list --json

Find the exact name value. Do not infer it from a process name, package name, or warning message. Codex configuration keys are logical server IDs, and a bundled plugin can own a server whose visible package name differs from the registration.

Save a redacted copy before editing. Keep the transport type, command or host, enabled state, timeout values, and tool filters. Remove bearer tokens, header values, environment-variable contents, and private URLs from anything you share.

Expected result: the target appears once and currently reports "enabled": true. If it is absent, stop. You may be looking at a different Codex home, a plugin-owned server, a project-level override, or another configuration layer.

2. Disable the server persistently

Open the active Codex configuration file and add enabled = false inside the existing block:

[mcp_servers.docs]
command = "docs-server"
args = ["--port", "4000"]
enabled = false

For a remote Streamable HTTP server, the same flag lives in its URL-based block:

[mcp_servers.linear]
url = "https://example.com/mcp"
enabled = false

Keep the existing transport fields. A disabled server still needs a structurally valid registration because Codex must parse the configuration before it can decide which servers to start.

The current Codex configuration reference defines mcp_servers.<id>.enabled as the switch for disabling a server without removing its configuration. The official CLI implementation also exposes the enabled state through codex mcp list --json, which gives you a direct verification surface instead of relying on the absence of a startup warning.

3. Verify in a fresh process

Run the inventory again:

codex mcp list --json

The target should still be present and should now report:

{
  "name": "docs",
  "enabled": false
}

The real output includes transport and authentication fields. The shortened example shows only the two assertions that matter here.

Then start a fresh Codex session. Do not use an already-running session as the only test because MCP clients and tool inventories are initialized at session startup. Confirm that:

1. the disabled server does not attempt to initialize;

2. its tools are absent from the new session;

3. other enabled servers still start normally; and

4. the original server block remains in config.toml.

If the server still starts, check for a later configuration layer overriding the value. Common causes include a different $CODEX_HOME, a project-specific configuration, a launch-time -c override, or a plugin-owned registration. Do not edit multiple files until codex mcp list --json proves which logical entry Codex actually resolved.

Disable it for one command only

For a one-off diagnostic, use a CLI override instead of changing the saved file:

codex -c 'mcp_servers.docs.enabled=false'

For codex exec, put the same -c override on that invocation. Verify the resolved state with the command form your installed version supports before using it in automation.

Disable each named server explicitly. The open Codex issue about -c 'mcp_servers={}' demonstrates why an empty table is not a reliable disable-all switch: configuration merging can treat it as an empty overlay and retain the saved servers. Explicit per-server flags are verbose, but their effect is inspectable.

Re-enable or remove the server

To resume the server, change the value to true or remove the enabled line if you want the default enabled behavior:

[mcp_servers.docs]
command = "docs-server"
args = ["--port", "4000"]
enabled = true

Open a fresh session and repeat the inventory and startup checks. If the original failure returns, disabling the server was a useful isolation result, not a repair. Investigate its command path, URL, authentication, initialization timeout, or provider availability.

Only remove the registration when you intend to discard it:

codex mcp remove docs

After removal, codex mcp get docs should report that no server with that name exists. Keep in mind that a plugin or host may contribute a separate registration. If remove says the server is not found while startup still names it, treat that as evidence of another ownership layer rather than deleting unrelated files.

Avoid these false fixes

Do not:

• set mcp_servers = {} and assume the saved table was replaced;

• delete config.toml to silence one server;

• erase OAuth or environment configuration when a reversible pause is enough;

• disable every server when one named startup failure is the symptom;

• confuse enabled = false with provider-side credential revocation;

• verify only in a session that was already running; or

• remove a plugin-owned server by hand without identifying its owning plugin and policy layer.

A reversible change plus a fresh-process check gives you a cleaner diagnosis. If startup improves with one server disabled, you have isolated a boundary. If nothing changes, restore it and continue with evidence instead of accumulating unrelated configuration changes.

Decide whether to keep owning this MCP setup

Pausing a server is useful when you own its local process or remote endpoint and intend to repair it. It does not reduce the long-term work of maintaining launch commands, credentials, OAuth callbacks, version compatibility, timeouts, and tool policy.

The local versus remote MCP server guide helps decide where that operational boundary should live. The MCP API keys versus OAuth guide covers the credential tradeoff. If your real job is to let an agent use a business service rather than operate an MCP server, the Aident Loadout setup guide shows the deeper managed path.

With Aident Loadout, the measurable next step is to connect one relevant integration, inspect one current Action schema, and preflight a bounded operation before execution. Follow the setup instructions and stop after a free, valid preflight if you are only evaluating the alternative. Success means you can compare the managed path without copying a provider secret into the prompt or deleting your existing Codex configuration.

Verification checklist

Before closing the change, confirm:

1. Did you record the exact logical server name from codex mcp list --json?

2. Does the server remain listed with enabled: false?

3. Did you test with a fresh Codex process?

4. Are the disabled server's tools absent while unrelated servers still work?

5. Did you preserve transport, timeout, and environment-variable-name configuration?

6. Did you avoid treating disablement as credential revocation?

7. Can you re-enable the server with one reviewed change?

Sources and refresh trigger

• OpenAI Codex configuration reference, including mcp_servers.<id>.enabled and tool filtering.

• OpenAI Codex MCP documentation, covering MCP configuration and CLI management.

• Codex MCP CLI implementation, including list, get, and remove behavior.

• Codex MCP list tests, including the structured enabled state and remove command.

• Codex issue 16045, documenting why an empty mcp_servers CLI override does not disable all saved servers.

Refresh this guide when Codex adds a supported disable-all switch, changes configuration precedence, changes the MCP list schema, or changes how plugin-owned MCP servers are enabled or removed.