How to add a URL-based MCP server to Codex

A remote Model Context Protocol (MCP) server exposes tools over HTTP while its provider runs the service. Codex can save the server's URL under a short name instead of launching a local server process.

URL registration changes the user-level Codex configuration, normally stored in ~/.codex/config.toml or under a custom CODEX_HOME. The CLI and IDE extension share that file when they use the same configuration environment; trusted projects can also supply their own MCP settings.

An installed Codex CLI and the provider's published streamable HTTP endpoint are required. Saving the address does not establish connectivity or grant access to the server's tools; authentication and tool availability depend on the provider.

1. Choose an unused server name for the provider's endpoint.

   The name example-docs identifies one entry in the configuration. The placeholder below represents the provider's MCP endpoint, rather than its documentation homepage; it is not a working server.

   https://mcp.example.com/mcp

   A saved URL can appear in configuration files and diagnostic output. Tokens, cookies, and other credentials do not belong in the URL.

2. Register the endpoint with its bearer-token environment variable name.

   $ codex mcp add example-docs \
     --url https://mcp.example.com/mcp \
     --bearer-token-env-var MCP_TOKEN
   Added global MCP server 'example-docs'.

   The URL and server name stand for your chosen endpoint and name. The optional bearer-token setting stores MCP_TOKEN as a variable name, without storing its value. When connecting to a token-protected server, Codex needs that variable in its launch environment. For a public server that needs no token, omit the bearer-token option. OAuth providers use a separate codex mcp login flow.

3. Verify the saved URL and authentication mapping for the new entry.

   $ 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 matching URL, streamable_http transport, and MCP_TOKEN variable name confirm the saved registration. A missing entry or different field value means the intended registration is absent or differs from the requested settings. The enabled flag describes configuration, rather than server health. New sessions read the saved entry at startup.