mcp_servers.<id>.url

Values

A string URL, no default. The auth options are sibling keys on the same table:

Key	Type	What it does
url	string	Endpoint for the streamable HTTP server
auth	oauth | chatgpt	Auth fallback after tokens and headers; default oauth
bearer_token_env_var	string	Env var holding the bearer token
http_headers	table	Static headers sent on every request
env_http_headers	table	Headers filled from env vars
scopes	array	OAuth scopes to request
oauth_resource	string	RFC 8707 resource parameter for login

OAuth plumbing sits at the top level of config.toml, not per-server: mcp_oauth_callback_port (default is an ephemeral port the OS picks), mcp_oauth_callback_url, and mcp_oauth_credentials_store (auto | file | keyring, default auto).

A working example:

[mcp_servers.github]
url = "https://github-mcp.example.com/mcp"
bearer_token_env_var = "GITHUB_TOKEN"
http_headers = { "X-Custom" = "value" }
env_http_headers = { "X-Auth" = "AUTH_ENV_VAR" }

codex mcp add github --url https://... writes the entry for you.

When to change it

1. Hosted servers like Linear or Notion: set url, then run codex mcp login <name>. Codex discovers the OAuth metadata at /.well-known/oauth-authorization-server, opens a browser, and catches the callback locally.
2. Internal service behind token auth: url plus bearer_token_env_var. The token stays in your environment and the config file stays committable.
3. Containers and SSH boxes: pin mcp_oauth_callback_port to a port you can actually forward, since the default random port is unreachable from a remote browser.

Gotchas

On 0.44.0, url-only servers would connect and then show “Tools: (none)” (#4707, 37 comments, Notion and Amap both). It was closed via PR #5298 in October 2025, which made MCP errors visible to the model so failures stopped being silent.

Older builds gated HTTP servers behind experimental_use_rmcp_client = true; current builds don’t need the flag, and #6995 tracks replacing it with [features].rmcp_client. On Windows specifically, old CLIs rejected url-only entries outright with “missing field command” (#4496), so upgrade before you start debugging the server side.

One thing the docs don’t spell out: whether deleting the server entry also purges its stored OAuth tokens (they live in the keychain or a file, not in config.toml). codex mcp logout <name> is the explicit path.

Related settings

• mcp_servers.<id>.command is the stdio counterpart
• mcp_servers.<id>.enabled parks a server without deleting it
• “handshaking with MCP server failed” when the connection dies at startup