How to Fix Codex MCP OAuth "Missing Required Issuer"

If codex mcp login completes browser consent and then fails with Authorization server response missing required issuer, check the Codex version before changing the MCP server. Codex CLI 0.143.0 through the current stable 0.146.0 have a confirmed callback regression: the authorization server can return the correct RFC 9207 iss value, but Codex drops it before validation. The fix is available in 0.147.0-alpha.1 while a stable release is pending as of August 4, 2026.

Do not disable issuer validation as a permanent fix. It protects OAuth clients from authorization-server mix-up attacks. Use a fixed Codex build, or use the last unaffected stable build only for the login, then verify the connection with a read-only call.

Confirm You Have This Exact Failure

Run these commands from a trusted terminal:

codex --version
codex mcp list
codex mcp login <server-name

The known regression has this sequence:

1. Codex discovers an HTTP MCP server and opens the authorization page.

2. Sign-in and consent finish in the browser.

3. The loopback page says authentication is complete.

4. The terminal reports:

Error: failed to handle OAuth callback

Caused by:
    Authorization server response missing required issuer:
    expected https://auth.example.com

5. codex mcp list still shows the server as not logged in.

If the browser never opens, the provider rejects the redirect URI, or the token exchange returns 400 or 401, you have a different OAuth failure. Use the failure-stage checklist in Fix MCP OAuth Callback Errors in Docker and WSL instead.

Use the Version Boundary to Classify the Error

Public reproductions in the Codex issue tracker establish this boundary:

The latest non-prerelease Codex release was 0.146.0 when this article was checked. That release is inside the affected range. A version alone is not proof that every issuer error is the client bug, so verify the server metadata next.

Verify the Issuer Without Exposing the Callback

First inspect the MCP server's protected-resource metadata. Replace the URL with the canonical MCP URL you configured in Codex:

curl -fsS 'https://mcp.example.com/.well-known/oauth-protected-resource' \
  | jq '{resource, authorization_servers}'

Expected result:

{
  "resource": "https://mcp.example.com/mcp",
  "authorization_servers": ["https://auth.example.com"]
}

Then inspect the advertised authorization server:

curl -fsS 'https://auth.example.com/.well-known/oauth-authorization-server' \
  | jq '{issuer, authorization_response_iss_parameter_supported, authorization_endpoint, token_endpoint}'

Expected result:

{
  "issuer": "https://auth.example.com",
  "authorization_response_iss_parameter_supported": true,
  "authorization_endpoint": "https://auth.example.com/authorize",
  "token_endpoint": "https://auth.example.com/token"
}

The returned authorization-response iss must match the metadata issuer with a simple string comparison. Scheme, hostname, port, path, and trailing slash matter. The July 28, 2026 MCP authorization specification explicitly says clients must not normalize case, default ports, trailing slashes, or percent encoding before this comparison.

Do not paste a real callback URL into a chat, issue, or log. It can contain an authorization code and state value. If you operate the server, record only whether iss was present and whether it matched the expected issuer; redact the rest.

Fix Option 1: Run the Fixed Codex Prerelease for Login

If your environment permits a prerelease, run the fixed package without replacing the global installation:

pnpm dlx @openai/codex@0.147.0-alpha.1 --version
pnpm dlx @openai/codex@0.147.0-alpha.1 mcp login <server-name>

Expected result:

Successfully logged in

Then return to your normal Codex binary and check the stored connection:

codex mcp list

Use this route only if you accept prerelease software. Pin the exact version for reproducibility, review the official release, and replace it with the first stable release that includes the fix.

Fix Option 2: Use the Last Unaffected Stable Build for the Login

If you cannot run a prerelease, the issue thread identifies 0.142.5 as the last unaffected stable release:

pnpm dlx @openai/codex@0.142.5 --version
pnpm dlx @openai/codex@0.142.5 mcp login <server-name>
codex mcp list

This avoids downgrading your global Codex installation. It is a compatibility bridge, not a long-term rollout plan. Existing tokens may continue to work in a newer client, but a refresh-token expiry can force another login. Move to the fixed stable release when it is available and repeat the verification.

Do not use an old build for unrelated agent work. Limit it to this known login step, then close it.

Do Not "Fix" the Authorization Server by Removing iss

Some server operators found that setting authorization_response_iss_parameter_supported to false made affected Codex versions proceed. That changes the security contract to accommodate a client defect.

RFC 9207 adds iss so a client can confirm which authorization server produced the response before it sends an authorization code to a token endpoint. The current MCP specification requires a client to reject a response that omits iss when the server advertises support. Turning the flag off or removing the callback parameter weakens that mix-up defense and can create different behavior across Claude, Codex, ChatGPT, VS Code, and other clients.

For a production MCP server:

• keep the external issuer consistent across protected-resource metadata, authorization-server metadata, the callback response, and token validation;

• derive public URLs from the external request origin when a reverse proxy serves more than one hostname;

• preserve the exact issuer string, including a meaningful path or trailing slash;

• test at least one fixed Codex build and one independent MCP client;

• use Cache-Control: no-store while debugging metadata changes so a stale issuer does not mask the fix.

If the fixed client reports an issuer mismatch instead of a missing issuer, correct the server or proxy configuration. Do not relax comparison rules.

Verify the Fix End to End

After login succeeds:

1. Run codex mcp list and confirm the named server is enabled and authenticated.

2. Start a new Codex session so it loads the updated credential state.

3. Ask for one harmless read-only operation, such as listing a small page of resources.

4. Confirm the result comes from the intended account and environment.

5. Check the MCP server or provider audit log for exactly one expected read.

6. Confirm no authorization code, access token, refresh token, or client secret appears in the terminal transcript or repository diff.

If login succeeds but the read returns 401, inspect token audience, resource URI, and scope. If the tool is absent, inspect MCP startup and discovery rather than repeating OAuth login. Local vs. Remote MCP Servers explains the transport boundary, while MCP API Keys vs. OAuth covers the authentication tradeoff.

A Managed Alternative When You Need the Service Now

If the provider is already available through Aident Loadout, you can keep its credential in Aident Vault and let Codex call a named Action instead of depending on the affected local MCP OAuth callback.

If the aident command is not installed, tell your coding agent: Follow https://aident.ai/SETUP.md.

From a trusted terminal:

aident account auth status
aident vault vault --action status
aident capabilities search \
  --query 'read-only Action for <your task>' \
  --types action

Inspect the selected Action and its cost before execution:

aident capabilities get <action-name>
aident capabilities preflight <action-name> --input '<reviewed-json-object>'

Expected result: authentication is ready, the Action contract identifies the provider connection and risk, and preflight returns valid input plus zero or disclosed credits without exposing a provider token. This does not repair the third-party MCP server. It gives the agent a separate managed execution path while you wait for the fixed stable Codex release.

Ready to verify one safe path? Set up Aident Loadout and preflight one read-only Action.

Sources

• OpenAI Codex issue 31573: OAuth authentication fails at issuer validation

• OpenAI Codex release 0.146.0

• OpenAI Codex release 0.147.0-alpha.1

• OpenAI Codex MCP login implementation

• Model Context Protocol authorization specification, 2026-07-28

• IETF RFC 9207: OAuth 2.0 Authorization Server Issuer Identification

• IETF RFC 9700: OAuth 2.0 Security Best Current Practice

Review this article after Codex ships a stable release newer than 0.146.0, issue 31573 closes, the MCP authorization specification changes its RFC 9207 requirements, or Aident Loadout changes its public authentication and capability workflow.