AI Research With OpenAI Codex and Rivul MCP

Overview

This workflow connects the Codex CLI to Rivul MCP for read-only scholarly paper search and citation metadata.

Codex registers with Rivul through dynamic client registration and signs in with PKCE browser authorization. It can then call search_papers, get_paper_details, and usage_status, and access ends when you disconnect the grant.

Client behavior can change between releases, so confirm your installed Codex version if a command or consent screen differs.

Before you start

1. Step 1: Use a Rivul AI account with Rivul MCP provisioned for the workspace you intend to approve.
2. Step 2: Open Rivul MCP once so the intended workspace is available during consent.
3. Step 3: Confirm your installed Codex version before treating a different prompt or consent screen as a fault.

Add the Rivul MCP server

1. Step 1: Add the production Streamable HTTP endpoint with the command below. Do not add bearer_token_env_var when you want browser authorization.
2. Step 2: Start login with explicit read-only Rivul MCP 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:read

Verify the connection

1. Step 1: Ask Codex to use Rivul MCP to search for Attention Is All You Need with a limit of 3 and relevance sorting.
2. Step 2: Confirm that the client used search_papers, returned three structured records, and preserved the source metadata.
3. Step 3: Ask Codex to call get_paper_details with the first result's openalex_id and confirm it returns the full record.
4. Step 4: Ask Codex to call usage_status. Confirm the usage it reports belongs to the workspace you approved.

Rivul MCP is metadata search, not hosted paper full text. Open the returned source or DOI before relying on a paper's findings. Searches are free under fair-use rate limits, and the usage read never counts toward usage.

Disconnect and confirm denial

1. Step 1: Run the logout command below. Codex removes its stored OAuth credentials.
2. Step 2: In Rivul MCP, open Authorized applications and disconnect the Codex grant. OpenAI's documentation does not state that logout revokes the grant on the server.
3. Step 3: Attempt usage_status again. A successful cleanup returns an authorization-required response instead of workspace usage.
4. Step 4: Remove the server entry if you no longer need Rivul MCP in Codex.

codex mcp logout rivul-atlas
codex mcp remove rivul-atlas

Troubleshooting

The loopback page says localhost refused to connect. This can appear briefly after approval when the client has already received the callback and closed its listener. Trust the Codex terminal result, then verify with an actual Rivul MCP tool call rather than with the browser tab.

Login reports authorization required. Rerun codex mcp login. If the wrong workspace appears, log out, remove the Rivul grant in Rivul MCP, and authorize again against the intended workspace.

Calls stop working after they previously succeeded. Read usage_status, which never counts toward usage, to tell a rate limit from a revoked grant.

• OpenAI Codex MCP documentation
• Model Context Protocol authorization specification
• Rivul MCP tool reference
• Codex and Rivul MCP walkthrough
• Open Rivul MCP