How to Connect OpenAI Codex to Rivul MCP

Quick answer

Rivul MCP exposes search_papers for normalized scholarly records, get_paper_details for one work's full record, andusage_status for the selected workspace's current MCP usage for the current UTC day. It does not give Codex your Rivul sign-in credentials, 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 the production run showed

On September 16, 2026, Rivul AI tested OpenAI Codex 0.154.0-alpha.6.2 against the production Rivul MCP endpoint. Codex completed Dynamic Client Registration and PKCE browser authorization, discovered both tools, returned three records for a bounded search, read the workspace usage, 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. The run predates get_paper_details, so the record lookup in step 3 was not part of it.

That retained run supports one precise claim: OpenAI Codex browser OAuth works with Rivul 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 Rivul MCP server

Use a confirmed Rivul AI account and open Rivul MCP once so the intended workspace is available on the consent screen. Register Rivul MCP 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 Rivul MCP'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.

1. Sign in to Rivul. Sign-in happens in the browser; your credentials are never entered into Codex.
2. Choose one workspace. The resulting grant is scoped to that workspace, not the whole account.
3. Review both scopes. search:read permits scholarly search; usage:read permits reading usage.
4. Approve and return. Codex receives the loopback callback and stores its own OAuth state locally.

Rivul MCP uses OAuth metadata discovery, Dynamic Client Registration, and PKCE for this 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 the Rivul MCP 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, one record lookup, and one usage read. A small explicit limit makes the result easy to inspect and keeps an unnecessarily large first request from counting against fair-use limits.

The retained run returned exactly three records and placed Attention Is All You Need first. It also returned the approved workspace's usage status. It predates get_paper_details, so confirm that call returns a full record in your own run. If Codex only lists the tools, continue to an actual tool call before relying on the connection.

What Codex receives

search_papers returns a short normalized record for each result from Rivul Index; get_paper_details returns the full record for one work. 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.

Open the DOI or source location and read the paper before using a result as evidence. Rivul MCP 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 revoked

Logging out removes Codex's stored OAuth credentials. Then revoke the matching grant under Authorized applications in Rivul MCP, MCP setup, because OpenAI's documentation does not state that logout revokes it on the server. Then retry usage_status. Successful cleanup returns an authorization-required response instead of workspace data.

Removing the local entry keeps Rivul MCP 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 Rivul MCP

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 a Rivul MCP tool, not by relying only on the final browser page.

Login reports authorization required

Rerun codex mcp login. If the wrong workspace appears, run codex mcp logout rivul-atlas, remove the Rivul grant in Rivul MCP, and authorize again against the intended workspace.

The server is configured but Rivul MCP tools do not appear

For the shorter command reference, open the Codex help guide for Rivul MCP. The Rivul MCP 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 (client configuration) · MCP authorization specification (OAuth and PKCE for remote HTTP servers).

Related: Open the Codex guide; Rivul MCP features.