How to add a URL-based MCP server to Codex

Adding a URL-based Model Context Protocol (MCP) server saves a remote streamable HTTP endpoint in Codex so a session can reach hosted tools or documentation without launching a local process. This is the right path when the server is published at an HTTP or HTTPS address instead of as a local command.

Current OpenAI Codex docs say Codex supports remote MCP servers in both the CLI and the IDE extension, and the saved configuration is shared between those clients. By default, the CLI writes the entry to ~/.codex/config.toml, where the server is stored under [mcp_servers.<name>] with a url value.

Current local verification with codex-cli 0.121.0 shows codex mcp add <name> --url <url> saving a streamable_http transport. Remote servers that expect an Authorization: Bearer header can be added with --bearer-token-env-var, and servers that support OAuth can be authenticated afterward with codex mcp login <server-name>.

Steps to add a URL-based MCP server to Codex:

Add the remote MCP endpoint with a short server name.
```
$ codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
Added global MCP server 'openaiDeveloperDocs'.
```
The same command shape works for any streamable HTTP MCP server. Replace openaiDeveloperDocs with your chosen server name and replace the URL with the published MCP endpoint.

Use --bearer-token-env-var TOKEN_ENV_VAR when the server expects a bearer token. Current codex mcp add –help output shows --env is only valid for stdio servers, not for URL-based servers.

Retrieve the saved entry in JSON to confirm that Codex stored the expected remote transport.

$ codex mcp get openaiDeveloperDocs --json
{
  "name": "openaiDeveloperDocs",
  "enabled": true,
  "disabled_reason": null,
  "transport": {
    "type": "streamable_http",
    "url": "https://developers.openai.com/mcp",
    "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
}

For a URL-based server, the decisive fields are transport.type = streamable_http and transport.url matching the endpoint you intended to save. A bearer-protected server also shows its bearer_token_env_var here.

List configured MCP servers and confirm the new entry is enabled.
```
$ codex mcp list
Name                 Url                                Bearer Token Env Var  Status   Auth
openaiDeveloperDocs  https://developers.openai.com/mcp  -                     enabled  Unsupported
```
The success state for this page is a row with the expected server name, URL, and enabled status. A public endpoint like OpenAI Docs MCP can still show Unsupported under Auth because it does not require a separate login flow.
Start Codex and run a prompt that should use the new MCP server.
```
$ codex
```
If the server advertises OAuth, run codex mcp login <server-name> after adding it and before relying on the integration. Current Codex MCP docs list bearer-token and OAuth authentication as supported features for remote MCP servers.

A prompt that clearly depends on the server's tools or content is the final verification. For the OpenAI Docs MCP example, asking for a current OpenAI docs field or option forces a real MCP lookup.