Troubleshooting and FAQ

For a connection named orchestration:

codex mcp logout orchestration
codex mcp login orchestration --scopes openid,profile,email,offline_access,mcp:context-picker

Use your connection's actual name. Complete the picker, open a new Codex session, and retry the read-only verification. If the picker still does not appear, report the client version and gateway URL.

Clear this connection's saved authorization and sign in again. Check for an x-auth-context header in your client configuration: it overrides the picker. Verify the returned account before making changes.

Browser logout alone does not clear the MCP client's saved credentials.

For an expired token or lost account selection, reauthorize the connection and repeat a read-only call. If this recurs after renewal, report that timing along with the error. Never send the access or refresh token.

An initial 401 with a WWW-Authenticate header is a normal part of OAuth discovery. Your client should continue to sign-in.

A persistent 401 after sign-in can indicate expired credentials or a token for a different environment. Check the gateway URL and reauthorize. A static X-MCP-Service-Token can list metadata but cannot authorize tools/call.

Check the environment, selected account, and whether your identity has access to the server. Read the accompanying error; a 403 alone does not identify its cause.

If it explicitly mentions MCP_REGISTRATION_HOST_ALLOWLIST, report it to the gateway/server owner. That is an operator configuration issue, not a reason to keep changing client credentials.

Refresh the client's tool list and confirm the server URL. An aggregate or group connection uses names such as orchestration__get_products; a direct server connection uses get_products.

An error about a missing __ delimiter means you used an unprefixed name on an aggregate connection. Copy the name returned by tools/list. Check any client-side tool allowlist if the tool remains absent.

Remote Claude connectors originate from Anthropic's infrastructure. They do not inherit your laptop's VPN connection. Use the gateway URL supplied for that client and ask your Magnite contact about network reachability. Your Claude organization may also need to enable the custom connector.

audit_unavailable means the gateway could not complete required audit handling. Report it to gateway support. A generic downstream error needs its accompanying detail to diagnose; it does not prove an authentication problem.

Retry a read only when appropriate. For a write, check whether the operation took effect before retrying it.

No. Gateway clients use their own OAuth sign-in flow. Streamr's direct /api/mcp embed-token integration is a separate path. Do not use its x-api-key instructions for a gateway OAuth connection.