How to remove a Codex MCP server

A stale Model Context Protocol (MCP) entry keeps a retired integration available to future tasks. Removing its saved Codex server entry prevents new sessions from loading that user-level registration while leaving other configured servers in place.

An installed Codex CLI and an existing server registration are required. The saved name identifies the entry to delete; a launcher command, URL, or package name is not a substitute. Inspection from the project where the server is used helps distinguish personal settings from a project's own configuration.

Removal changes configuration without uninstalling a local launcher, stopping a separately running server, or revoking credentials at its provider. An already-open Codex session can retain the tools it initialized until it is reopened. A temporary pause can instead use a disabled entry, preserving its connection settings.

1. List the saved MCP server names from the project where the server is used.

   $ codex mcp list
   Name          Url                              Bearer Token Env Var  Status   Auth
   example-docs  https://mcp.example.com/mcp      MCP_TOKEN             enabled  Bearer token
   private-docs  https://mcp.example.com/private  -                     enabled  Unknown

   The Name column supplies the removal target. The placeholder example-docs represents the entry being retired; private-docs represents an unrelated entry that should remain. Listed URLs and authentication labels describe saved settings rather than connection health.

2. Confirm that the named entry points to the server you intend to remove.

   $ codex mcp get example-docs
   example-docs
     enabled: true
     transport: streamable_http
     url: https://mcp.example.com/mcp
     bearer_token_env_var: MCP_TOKEN
     http_headers: -
     env_http_headers: -
     http_headers_helper: -
     remove: codex mcp remove example-docs

   A local stdio entry shows its launcher command and arguments instead of a URL. Details can contain private endpoints, environment values, or headers, so sensitive output belongs in private records.

   Deletion discards the named entry's saved connection settings. Those settings are needed to add it again if the removal was mistaken. A temporary pause can keep the entry with enabled = false in its configuration table.
   Related: How to add a URL-based MCP server to Codex

3. Remove the selected server entry from the user-level configuration.

   $ codex mcp remove example-docs
   Removed global MCP server 'example-docs'.

   The global configuration normally lives in ~/.codex/config.toml, or in config.toml under a custom CODEX_HOME. The CLI and IDE extension share it when they use the same configuration environment.

4. Check that the removed name no longer resolves.

   $ codex mcp get example-docs
   Error: No MCP server named 'example-docs' found.

   This missing-name error returns a nonzero exit status. If the entry still resolves inside a trusted project, that project's .codex/config.toml can supply a server with the same name. Global removal leaves that project entry intact.

5. Verify that the remaining inventory omits only the retired entry.

   $ codex mcp list
   Name          Url                              Bearer Token Env Var  Status   Auth
   private-docs  https://mcp.example.com/private  -                     enabled  Unknown

   The unrelated server remains listed and example-docs is absent. If the removed entry was the only configured server, the inventory instead reports No MCP servers configured yet.