Rivul Atlas · Verified client run
How to connect Claude Code to Rivul Atlas MCP
Production-tested browser OAuth and dedicated-key workflows for giving Claude Code read-only scholarly search and Atlas usage access to one Rivul workspace.
In this article
Quick answer
https://rivul.ai/mcp as a remote HTTP server, choose browser OAuth or a dedicated workspace key, confirm search_papers andusage_status, then revoke that grant or key when the connection is no longer needed.Rivul Atlas gives Claude Code two read-only MCP tools. One searches normalized scholarly records. The other reports the selected workspace's Atlas MCP-credit balance without consuming a credit. The connection does not give Claude Code a Rivul password, access to another workspace, or permission to edit research data.
This supports an AI agent research workflow with research-paper discovery, citation metadata, and source links. Claude Code still needs to open and assess the original paper before treating a record as evidence for a claim.
What we verified in production
On September 16, 2026, Rivul AI tested Claude Code 2.1.273 against the production Atlas endpoint. Claude Code completed Client ID Metadata Document discovery and PKCE browser authorization, discovered both tools, returned three records for a bounded search, read usage, then lost access after its grant was revoked. A second run repeated the tool calls with a temporary MCP key and returned HTTP 401 after the key was revoked.
That evidence supports two precise compatibility claims: Claude Code browser OAuth and dedicated MCP keys work with Rivul Atlas. The temporary key, local server entries, transfer files, and OAuth grants were removed after the run. No credentials are retained in the published evidence.
1. Add the Atlas MCP server
You need a verified Pro or Ultimate Rivul AI account and a workspace you can identify on the consent screen. Add Atlas at user scope so the private connection is available across your own Claude Code projects without writing it to a project file.
Terminalclaude mcp add --scope user --transport http rivul-atlas 'https://rivul.ai/mcp'Anthropic's Claude Code MCP documentation recommends remote HTTP for cloud services and documents user scope for private, cross-project servers. Do not commit access tokens or a personal server entry to a shared.mcp.json file.
2. Authorize one Rivul workspace
Start Claude Code, open /mcp, select rivul-atlas, and authenticate. Claude Code follows the endpoint's authorization metadata and opens Rivul in the browser. Choose the intended workspace and review the two requested read scopes before approving access.
- Sign in to Rivul. The password remains with Rivul; it is never entered into Claude Code.
- Choose one workspace. The resulting grant is scoped to that workspace instead of the whole account.
- Review the scopes.
search:readpermits scholarly search andusage:readpermits the usage balance. - Approve and return. Claude Code receives the loopback callback and stores its own OAuth credentials.
The browser path uses PKCE. In the MCP authorization specification, PKCE binds the authorization code to the client that created the verifier and challenge. The approved grant can still be revoked independently from Rivul Atlas.
3. Verify both Atlas tools
Discovery alone proves that Claude Code can see the tool contracts. It does not prove the selected workspace can execute them. Run one bounded search and one usage read.
Prompt Claude CodeUse Rivul Atlas search_papers to search for "Attention Is All You Need".
Set limit to 3 and sort to relevance. Report the result count and first title.
Then call usage_status and report the workspace plan and remaining MCP credits.The retained production run returned exactly three results and placed Attention Is All You Need first. It also returned the selected workspace's usage status. Avoid an unbounded first test: a small explicit limit makes the result count easy to inspect and avoids spending credits on a larger retrieval.
Alternative: connect with a dedicated MCP key
A dedicated key is useful when browser sign-in is not appropriate for a managed environment. The key belongs to one Atlas workspace and is shown once. Create it under Atlas Access keys, load it into RIVUL_ATLAS_MCP_KEY through the environment that starts Claude Code, and keep it out of shell history, project files, screenshots, logs, and chat prompts.
Terminal · literal environment referenceclaude mcp add --scope user --transport http rivul-atlas-key 'https://rivul.ai/mcp' \
--header 'Authorization: Bearer ${RIVUL_ATLAS_MCP_KEY}'Run the same bounded search and usage_status check. The retained Claude Code key-mode run discovered and called both tools, returned the same three-result search with the correct first title, and read the workspace usage balance. After the temporary key was revoked, a retained replay returned HTTP 401 with Invalid Rivul Atlas key. Atlas then showed zero active MCP keys.
Finish by removing rivul-atlas-key, deleting the environment secret, and clearing any temporary transfer material. The verification run retained none of those credentials.
What Claude Code receives
search_papers returns structured scholarly metadata. Availability varies by record, so Claude Code should not imply that every field is present or that a metadata match verifies a paper's findings.
| Identity | OpenAlex identifier, title, and up to eight author names |
|---|---|
| Publication | Year, date, venue, work type, topic, and field when available |
| Discovery context | Snippet, citation count, relevance or 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 Claude Code find a record; it does not judge whether a paper is correct or whether it supports a draft claim.
4. Disconnect and confirm access is dead
In Claude Code's /mcp menu, select the Atlas server and clear its authentication. In Rivul Atlas, open Authorized applications and revoke the matching grant. Then attempt usage_status again. A successful cleanup produces an authorization-required response instead of returning workspace usage. For key mode, revoke the key under Atlas Access keys and repeat the same call. The verified replay returned HTTP 401 rather than workspace data.
Local server cleanupclaude mcp remove rivul-atlas
claude mcp remove rivul-atlas-keyRemoving the server entry is useful when you no longer want Atlas listed. Revoking the grant is the security boundary: it invalidates the authorization independently of the local configuration.
Troubleshooting Claude Code and Atlas
The browser says localhost refused to connect
Return to Claude Code first. Its temporary loopback listener may already have received the callback and closed. If Claude Code still shows authentication as incomplete, copy the full callback URL from the browser and use the URL prompt Claude Code presents. Anthropic documents this recovery path in its MCP guide.
The Atlas tools appear but calls fail
Clear authentication, revoke the old Rivul grant, and authorize again against the intended workspace. Confirm the account remains eligible for Atlas and that the consent screen includes both search:read and usage:read.
A dedicated key returns HTTP 401
RIVUL_ATLAS_MCP_KEY from the environment that launched it and that the configuration preserves the literal environment reference. Never paste the complete key into diagnostics. If Atlas shows the key as revoked, create a new one instead of attempting to recover the old value.For the shorter command reference, open the Claude Code Atlas help guide. The Atlas technical overview explains how this client flow relates to the REST API, other MCP clients, and returned metadata.