DocumentationConnect OpenAI Codex to Rivul Atlas
Public guide
Connect OpenAI Codex to Rivul Atlas
A verified Codex browser-OAuth workflow for read-only scholarly search and Atlas usage status, with exact commands and revocation checks.
On this page
What was verified
Status: Verified. Codex completed dynamic client registration, PKCE browser authorization, discovery of search_papers and usage_status, one three-result search for Attention Is All You Need, one usage read, OAuth logout, and a denied request after revocation.
The retained run used Codex 0.154.0-alpha.6.2. Client behavior can change, so confirm your installed version if a command or consent screen differs.
Add the Atlas server
Use a verified Pro or Ultimate Rivul AI account and open Rivul Atlas once so the intended workspace is available.
Add the production Streamable HTTP endpoint with the command below. Do not add bearer_token_env_var when you want browser authorization.
Start login with explicit read-only Atlas scopes. Your browser opens Rivul so you can choose one workspace and approve access.
codex mcp add rivul-atlas --url https://rivul.ai/mcp
codex mcp login rivul-atlas --oauth-client-registration dcr --scopes search:read,usage:readVerify the connection
Ask Codex to use Rivul Atlas to search for Attention Is All You Need with a limit of 3 and relevance sorting.
Confirm that the client used search_papers, returned three structured records, and preserved the source metadata.
Ask Codex to call usage_status. Confirm the plan and remaining credits match the workspace you approved.
Atlas is metadata search, not hosted paper full text. Open the returned source or DOI before relying on a paper's findings.
Disconnect and confirm denial
Run the logout command below. Codex removes its stored OAuth credentials and calls Rivul's revocation endpoint.
Attempt usage_status again. A successful cleanup returns an authorization-required response instead of workspace usage.
Remove the server entry if you no longer need Atlas in Codex.
codex mcp logout rivul-atlas
codex mcp remove rivul-atlasTroubleshooting and official references
A browser loopback page can briefly say localhost refused to connect after approval if the client has already received the callback and closed its listener. Trust the Codex terminal result, then verify with an actual Atlas tool call.
If login reports authorization required, rerun codex mcp login. If the wrong workspace appears, log out, remove the Rivul grant in Atlas, and authorize again against the intended workspace.
Something here wrong or missing? Email support@rivul.ai.