How to add an MCP server URL in Codex

Adding an MCP server URL makes Codex aware of a remote or local tool backend, turning a raw endpoint into a named server entry that can be reused. A saved entry also avoids retyping URLs and ports when switching between environments.

Codex stores MCP servers in /~/.codex/config.toml, which is shared between the CLI and IDE extension. The codex mcp add subcommand records the server name and URL for streamable HTTP servers, and codex mcp list shows the stored transport, endpoint, and status.

Server URLs must be reachable from the host running Codex, including any container/VM networking, firewall rules, or proxy settings in between. Prefer loopback URLs such as http://127.0.0.1:9010 for local servers to avoid exposing listening ports on a LAN, and keep secrets out of URLs since command history and process listings can reveal them.

1. Pick a unique, descriptive server name for the entry.

   Short names work best in prompts and commands, for example analytics or playwright-mcp.

2. Add the MCP server URL under a unique, descriptive name.

   $ codex mcp add analytics --url http://127.0.0.1:9010

   Avoid embedding tokens or passwords in the URL because shell history and process listings can expose them.

   Add --bearer-token-env-var when the server expects an Authorization bearer token.

   Use codex mcp add <name> -- <command> for stdio servers.

3. Start an OAuth login for servers that require it.

   $ codex mcp login analytics --scopes read:docs,read:issues

   Use codex mcp logout <name> to remove cached OAuth credentials.

4. Retrieve the saved entry in JSON to confirm the stored transport and URL.

   $ codex mcp get analytics --json
   {
     "name": "analytics",
     "enabled": true,
     "disabled_reason": null,
     "transport": {
       "type": "streamable_http",
       "url": "http://127.0.0.1:9010",
       "bearer_token_env_var": null,
       "http_headers": null,
       "env_http_headers": null
     },
     "enabled_tools": null,
     "disabled_tools": null,
     "startup_timeout_sec": null,
     "tool_timeout_sec": null
   }

5. List MCP servers to confirm the new entry is stored.

   $ codex mcp list
   Name            Url                    Bearer Token Env Var  Status   Auth
   analytics       http://127.0.0.1:9010  -                     enabled  Unsupported

   The Url column shows the configured endpoint, and Status indicates whether the entry is active.