Rivul Atlas · Verified client run
How to connect OpenAI Codex to Rivul Atlas MCP
A production-tested OAuth workflow for giving Codex read-only scholarly search and Atlas usage access to one Rivul workspace.
In this article
Quick answer
https://rivul.ai/mcp as a remote server, start Codex's OAuth login, choose one Rivul workspace, and verify both read-only Atlas tools. When the connection is no longer needed, log out, revoke the grant, and confirm that a retained request is denied.Rivul Atlas exposes search_papers for normalized scholarly records and usage_status for the selected workspace's MCP-credit balance. It does not give Codex a Rivul password, manuscript access, or permission to edit library content. Search results are metadata and source locations; they are not proof that a paper supports a claim.
What we verified in production
On September 16, 2026, Rivul AI tested OpenAI Codex 0.154.0-alpha.6.2 against the production Atlas endpoint. Codex completed Dynamic Client Registration and PKCE browser authorization, discovered both tools, returned three records for a bounded search, read the workspace usage balance, and lost access after logout and grant revocation. The client did not expose the negotiated MCP protocol version in the retained output, so this article does not infer one.
That retained run supports one precise claim: OpenAI Codex browser OAuth works with Rivul Atlas MCP. The disposable workspace grant and local Codex server entry were removed after the run. The evidence contains no token, callback code, cookie, client secret, or personal account information.
1. Add the Atlas server
Use a verified Pro or Ultimate Rivul AI account and open Atlas once so the intended workspace is available on the consent screen. Register Atlas under a stable local name. Do not configure bearer_token_env_var when you want browser OAuth; that field selects dedicated-key mode instead.
Codex stores local MCP configuration in ~/.codex/config.toml. Keep a personal OAuth server entry out of a shared repository. The hosted ChatGPT website does not read a machine's local Codex configuration.
2. Authorize one Rivul workspace
Start the login flow with Atlas's two explicit read-only scopes. Codex opens Rivul in the browser, where you sign in, choose one workspace, review access, and approve the connection.
- Sign in to Rivul.Your password remains with Rivul and is never entered into Codex.
- Choose one workspace.The resulting grant is scoped to that Atlas workspace, not the whole account.
- Review both scopes.
search:readpermits scholarly search;usage:readpermits the usage balance. - Approve and return.Codex receives the loopback callback and stores its own OAuth state locally.
Atlas uses OAuth metadata discovery, Dynamic Client Registration, and PKCE for this verified flow. PKCE binds the authorization code to the client that began the request. The Rivul grant remains independently revocable even if a Codex configuration entry still exists.
3. Verify both Atlas tools
Tool discovery proves that Codex can see the contracts, but not that the approved workspace can execute them. Ask Codex to run one bounded search and one usage read. A small explicit limit makes the result easy to inspect and avoids spending credits on an unnecessarily large first request.
The retained run returned exactly three records and placed Attention Is All You Need first. It also returned the approved workspace's usage status. If Codex only lists the tools, continue to an actual tool call before describing the connection as verified.
What Codex receives
search_papers returns normalized scholarly metadata from Rivul Index. Field availability varies by record. Codex should distinguish a missing field from a negative finding and should not present metadata as if it had read or validated the full paper.
| Identity | OpenAlex identifier, title, and up to eight author names |
|---|---|
| Publication | Year, publication date, venue, work type, topic, and field when available |
| Discovery context | Snippet, citation count, selected sort order, and pagination metadata |
| Source locations | DOI, landing page, and open-access URL when the index has them |
| Access signal | Whether the record is marked open access; Atlas does not host publisher full text |
Open the DOI or source location and read the paper before using a result as evidence. Atlas helps Codex locate a scholarly record; it does not determine whether the paper is correct or whether it supports a draft claim.
4. Disconnect and confirm access is dead
Logging out removes Codex's stored OAuth state and invokes Rivul's revocation path. Also confirm the matching grant is no longer active under Atlas Authorized applications. Then retry usage_status. Successful cleanup returns an authorization-required response instead of workspace data.
Removing the local entry keeps Atlas out of future Codex sessions. Revoking the Rivul grant is the security boundary: it invalidates access independently of the local configuration. The retained production run confirmed denial after revocation.
Troubleshooting Codex and Atlas
The browser briefly says localhost refused to connect
Return to the Codex terminal first. The temporary loopback listener may already have received the callback and closed. Confirm success by running an Atlas tool, not by relying only on the final browser page.
Login reports authorization required
Run codex mcp logout rivul-atlas, revoke the incomplete grant in Atlas, and start login again. If the wrong workspace appeared, choose the intended workspace during the new consent flow.
The server is configured but Atlas tools do not appear
codex mcp login. A bearer_token_env_var entry selects dedicated-key mode instead. Do not paste a complete key into diagnostics or a project file.OpenAI's official Codex MCP documentation describes the client configuration. The official Model Context Protocol authorization specification explains the OAuth and PKCE boundary used by remote HTTP servers. For the shorter reference, use the Codex Atlas help guide. The Atlas technical overviewexplains how this workflow relates to the REST API and other MCP clients.
These commands were cross-checked against OpenAI's official Codex MCP documentation on September 17, 2026. The compatibility result above comes from Rivul's retained production run, not from documentation alone.
Official references: OpenAI Codex MCP documentation · MCP authorization specification.