How to Connect Claude Code to Rivul MCP

Quick answer

Rivul MCP gives Claude Code three read-only MCP tools. One searches normalized scholarly records, one returns the full record for a single work, and the third reports the selected workspace's Rivul MCP usage for the current UTC day without counting toward it. The connection does not give Claude Code your Rivul sign-in credentials, access to another workspace, or permission to edit research data.

That gives an AI agent research workflow 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 the production run showed

On September 16, 2026, Rivul AI tested Claude Code 2.1.273 against the production Rivul MCP 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. These retained runs predate get_paper_details, so the record lookup in step 3 was not part of them.

That evidence supports two precise compatibility claims: Claude Code browser OAuth and dedicated MCP keys work with Rivul MCP. 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 Rivul MCP server

You need a confirmed Rivul AI account and a workspace you can identify on the consent screen. Add Rivul MCP 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

Run claude mcp login rivul-atlas from the shell, or 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. Afterward, claude mcp list should show the server as connected.

Terminalclaude mcp login rivul-atlas
claude mcp list

1. Sign in to Rivul. Sign-in happens in the browser; your credentials are never entered into Claude Code.
2. Choose one workspace. The resulting grant is scoped to that workspace instead of the whole account.
3. Review the scopes. search:read permits scholarly search and usage:read permits reading usage.
4. 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 MCP.

3. Verify the Rivul MCP 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, one record lookup, and one usage read.

Prompt Claude CodeUse Rivul MCP 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.
Call get_paper_details with the first result's openalex_id and report its venue if present.
Then call usage_status and report today's MCP usage for this workspace.

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. It predates get_paper_details, so confirm that call returns a full record for the same openalex_id in your own run. Avoid an unbounded first test: a small explicit limit makes the result count easy to inspect and keeps a larger retrieval from counting against fair-use limits.

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 workspace and is shown once. Create it under Rivul MCP, 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. After the temporary key was revoked, a retained replay returned HTTP 401 with Invalid Rivul Atlas key. Rivul MCP then showed zero active MCP keys.

Finish by removing rivul-atlas-key, deleting the environment secret, and clearing any temporary transfer material. The production run retained none of those credentials.

What Claude Code receives

search_papers returns a short record for each result;get_paper_details returns the full record for one work. Availability varies by record, so Claude Code should not imply that a record includes every field or that a metadata match verifies a paper's findings.

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

In Claude Code's /mcp menu, select the Rivul MCP server and clear its authentication. In Rivul MCP, open MCP setup, find 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 Rivul MCP, Access keys, and repeat the same call. The production replay returned HTTP 401 rather than workspace data.

Local server cleanupclaude mcp logout rivul-atlas
claude mcp remove rivul-atlas
claude mcp remove rivul-atlas-key

Remove the server entry when you no longer want Rivul MCP listed. Revoking the grant is the security boundary: it invalidates the authorization independently of the local configuration.

Troubleshooting Claude Code and Rivul MCP

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 Rivul MCP 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 Rivul MCP and that the consent screen includes both search:read and usage:read.

A dedicated key returns HTTP 401

For the shorter command reference, open the Claude Code help guide for Rivul MCP. The Rivul MCP technical overview explains how this client flow relates to the REST API, other MCP clients, and returned metadata.

Related: Open the Claude Code guide; Rivul MCP features.