Codex | 7 min read | 2026-08-27 | By Variant Team

Codex MCP OAuth Login: Troubleshooting and Reauth Guide

Fix a Codex MCP OAuth login that stalls, expires, or hides tools. Check auth state, run reauth, request scopes, and configure headless access.

Author: Variant Team. Variant is built by a small team working on HTML-native presentation tools, MCP workflows, and agent-editable decks.

Your remote MCP server appears in Codex, but its tools do not work. The browser may never open, the callback may stall, or codex mcp list may say Not logged in.

Adding a server and authenticating with it are separate steps. Read the auth state first, then choose browser login, reauth, or an environment-backed bearer token.

#Quick answer

Run codex mcp login <name> to start the OAuth flow for a streamable HTTP MCP server. To force Codex MCP reauth, run codex mcp logout <name> and then codex mcp login <name>. Use codex mcp list before and after login to confirm the server's auth state.

#Check the server before changing anything

First, confirm that Codex knows about the server:

codex mcp list
codex mcp get <name>

codex mcp list separates stdio and HTTP servers and includes Status and Auth columns. codex mcp get <name> shows one saved definition. OAuth login applies to a remote HTTP server, not every local stdio process.

Read the Auth value this way:

Auth value	What it means	What to do
`Not logged in`	Codex has the HTTP server definition but no active OAuth login for it.	Run `codex mcp login <name>`.
`OAuth`	Codex recognizes OAuth authentication for the server.	If tools still fail, inspect scopes and server status.
`Unsupported`	The server entry does not use a supported OAuth flow. This is expected for stdio servers that do not speak OAuth.	Do not try browser login. Check the stdio command and environment instead.

Do not treat Unsupported as a universal failure. A local stdio server can work without OAuth. If you meant to add a remote server, confirm that its definition has a url rather than command and args. The Codex MCP setup guide covers HTTP connections.

For a remote server already named example, run:

codex mcp login example

Codex discovers the authorization server, registers a client dynamically when supported, opens a browser for approval, and stores a token that can refresh. The authorization provider controls the approval screen and permitted access.

Variant follows this pattern with Clerk and Dynamic Client Registration. You do not need to copy a token into Codex for the normal browser flow.

When an existing login looks stale, use the full reauth cycle:

codex mcp logout example
codex mcp login example

After the browser flow completes, run codex mcp list again. If the server still says Not logged in, diagnose the callback or local configuration before repeating login.

#Request the scopes the server expects

A login can succeed while some tools remain unavailable. The authorization server may have granted fewer scopes than the MCP server expects for those tools.

Request known scopes as a comma-separated list:

codex mcp login example --scopes scope_a,scope_b

Use only scopes documented by the server operator. Do not guess names from tool names. A tool called deck.export, for example, does not prove that a scope named deck.export exists.

If you change the requested scopes, log out and log in again so the new authorization request is clear. Then reconnect the Codex session and check the tool list. For a presentation server, the MCP tools reference helps separate an authentication problem from a tool that the server does not provide.

#Add servers with special OAuth requirements

Most remote MCP servers can use discovery and dynamic registration. Some require a client that the operator registered in advance. Others require an explicit OAuth resource parameter.

Codex supports both cases when you add the HTTP server:

codex mcp add example \
  --url https://example.com/mcp \
  --oauth-client-id <CLIENT_ID>

For a server that documents an RFC 8707 resource value:

codex mcp add example \
  --url https://example.com/mcp \
  --oauth-resource <RESOURCE>

These flags solve server-specific requirements. They are not generic fixes for every failed callback. Only set the value supplied by the server operator. If the server documentation says nothing about a client ID or resource, start with the plain --url form.

#Use a bearer token in headless environments

A browser login is awkward in CI, a container, or a remote machine without an interactive browser. For those cases, tell Codex which environment variable contains the bearer token:

export EXAMPLE_MCP_TOKEN="<token>"
codex mcp add example \
  --url https://example.com/mcp \
  --bearer-token-env-var EXAMPLE_MCP_TOKEN

Codex stores the environment variable name, not the token value. The secret stays out of config.toml unless you paste or commit it elsewhere.

Your CI secret manager should inject EXAMPLE_MCP_TOKEN into the process that runs Codex. If a headless job can list the server but cannot call tools, confirm that the variable exists in that same process and that the token carries the access the server requires.

Browser OAuth is still the better choice for an interactive workstation because refresh is part of the normal login flow. A bearer token is the better choice when no person can complete a browser prompt. The broader guide to adding an MCP server to Codex explains when HTTP and stdio setups differ.

#Match the symptom to the fix

Symptom	Likely check	Practical fix
The browser never opens	Confirm the server is HTTP and `Auth` says `Not logged in`.	Run `codex mcp login <name>` from an interactive terminal. If it still stalls, run `codex doctor`.
The browser opens and then nothing happens	The approval may have completed while the local callback failed.	Return to the terminal, then retry the logout and login cycle. Check local browser or network restrictions if the callback fails again.
Tools are missing after a successful login	The granted scopes may not cover those tools, or the server may not expose them.	Reauthenticate with documented `--scopes`, then reconnect and inspect the tool list.
The token expired mid-session	The current session may not have recovered with its refreshable token.	Reconnect first. If that fails, run `codex mcp logout <name>` followed by `codex mcp login <name>`.
The server works in one project but not another	The two shells may use different Codex homes or environments.	Compare `CODEX_HOME`, `codex mcp list`, and required token variables in both shells.
The server shows `disabled`	The saved server is not active, so authentication is not the first problem.	Inspect `codex mcp get <name>` and the saved definition. Remove and add the server again if you cannot identify why it is disabled.

Start with observable state before deleting configuration. If the OAuth provider rejects the request, use its real message and the server's documentation. There is no universal MCP error code to assume.

#Know where Codex keeps MCP state

Codex stores server definitions in ~/.codex/config.toml, under a table named [mcp_servers.<name>]. An HTTP entry uses a url. A stdio entry uses command, args, and optionally an environment table.

CODEX_HOME relocates the whole Codex configuration directory. This is useful for isolation, but it can also explain why a server appears in one terminal and disappears in another. Check it before copying config files:

echo "$CODEX_HOME"
codex mcp list

Avoid hunting for an assumed token file. Use the supported login and logout commands.

When the definition looks right but auth still behaves strangely, run:

codex doctor

codex doctor diagnoses installation, configuration, and authentication issues. It is the right next step after you confirm the server name, transport, and auth state.

#Connect Codex to Variant

Variant is a remote, streamable HTTP MCP server. Add it with the hosted endpoint:

codex mcp add variant --url https://mcp.variant.art/mcp
codex mcp login variant
codex mcp get variant

The login opens the Clerk-backed OAuth flow. After approval, codex mcp get variant confirms the saved server definition, and codex mcp list shows the current auth state. Variant's MCP tools can then create, inspect, edit, preview, and export HTML-native presentation decks. The presentation MCP documentation lists the supported setup path.

Variant is not the right choice if your real goal is to authenticate against an unrelated MCP server or keep a presentation inside Google Slides. Use that server's own documentation, or a Google Slides workflow when Google Slides must remain the source of truth. Variant fits when Codex should work on editable HTML and CSS slides through presentation-aware tools.

#FAQ

Run codex mcp login <name> for a remote HTTP MCP server already saved in Codex. Complete the browser approval, then run codex mcp list to check the Auth column.

#How do I reauthenticate an MCP server in Codex?

Run codex mcp logout <name> and then codex mcp login <name>. This clean reauth cycle is useful when a previous grant is stale, a token no longer works, or requested scopes changed.

#Why does Codex say an MCP server is not logged in?

Not logged in means Codex has the remote HTTP server definition but no active OAuth login for it. Run codex mcp login <name>, complete the browser flow, and check codex mcp list again.

#Why does the Auth column say Unsupported?

Unsupported means the entry does not use a supported OAuth flow. This is expected for stdio MCP servers that do not speak OAuth, so check the local command and environment rather than trying browser login.

#Can Codex use MCP authentication without a browser?

Yes. Add an HTTP server with --bearer-token-env-var <ENV_VAR> and inject the token through that environment variable. Codex stores the variable name in config.toml, not the secret token value.

#Where is the Codex MCP configuration stored?

Codex stores MCP server definitions in ~/.codex/config.toml under [mcp_servers.<name>]. Setting CODEX_HOME relocates the Codex configuration directory, which can make different shells appear to have different server lists.

#The short version

Start with codex mcp list, then run codex mcp login <name> when an HTTP server says Not logged in. Use logout followed by login for reauth, documented scopes for missing access, and an environment-backed bearer token for headless jobs. Run codex doctor when the saved transport and auth state look correct but login still fails. Variant is a good fit for Codex-authored HTML slide decks, but use another server when your work belongs in its native system.

Next step

Use Codex to build your next deck

Connect Codex to the Variant MCP server, create a short deck, render a preview, then revise one slide.

Connect Codex to the editor Read the setup guide