Connect Claude Code to Rivul MCP

Overview

Claude Code connects to Rivul MCP through browser OAuth or a dedicated MCP key. Either way it can call search_papers, get_paper_details, and usage_status, all read-only, and access ends when you revoke the grant or the key.

Client behavior changes between releases, so confirm your installed Claude Code version if a command below differs from what your build accepts.

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 that Rivul MCP workspace once in the browser so it is available to choose during consent.
3. Step 3: Confirm your installed Claude Code version. Client behavior changes between releases, so a command below can differ from what your build accepts.

Add the server and sign in

1. Step 1: Add the production remote HTTP server at user scope. Omit an Authorization header to use browser OAuth.
2. Step 2: Start login with claude mcp login, or open /mcp inside Claude Code and authenticate. Claude Code opens Rivul, where you sign in, choose one workspace, and approve the two read-only scopes.
3. Step 3: List your servers and confirm Rivul MCP is connected before asking for research.

claude mcp add --scope user --transport http rivul-atlas https://rivul.ai/mcp
claude mcp login rivul-atlas
claude mcp list

Verify the connection

1. Step 1: Ask Claude Code to use Rivul MCP to search for Attention Is All You Need with a result limit of 3.
2. Step 2: Confirm the client calls search_papers and returns three structured paper records rather than answering from general model knowledge.
3. Step 3: Ask it to call get_paper_details with the first result's openalex_id and confirm it returns the full record.
4. Step 4: Ask it to call usage_status and confirm the usage it reports belongs to the workspace you approved.

Rivul MCP returns scholarly metadata and source locations. Open the 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.

Connect with a dedicated key

1. Step 1: Create a new MCP key in Rivul MCP for this Claude Code connection only. Copy it once into a private environment variable; do not reuse a production automation key.
2. Step 2: Add a separate Claude server entry whose Authorization header references the environment variable. Keep the complete key out of commands, project files, logs, screenshots, and shell history.
3. Step 3: Confirm the server discovers search_papers and usage_status, then run the same bounded three-result search and one usage read.

claude mcp add --scope user --transport http rivul-atlas-key https://rivul.ai/mcp --header 'Authorization: Bearer ${RIVUL_ATLAS_MCP_KEY}'
claude mcp get rivul-atlas-key
claude mcp list

Revoke and verify the key

1. Step 1: In Rivul MCP, Access keys, revoke the temporary key immediately after the two tool calls pass.
2. Step 2: Repeat usage_status through the same Claude entry. A revoked key returns HTTP 401 Invalid Rivul Atlas key.
3. Step 3: Confirm Rivul MCP shows 0 of 1 active MCP keys, remove the Claude entry, unset the environment variable, and clear any temporary clipboard value.

claude mcp remove rivul-atlas-key
unset RIVUL_ATLAS_MCP_KEY

Disconnect browser access

1. Step 1: In Rivul MCP, open Authorized applications and disconnect the Claude grant.
2. Step 2: Ask Claude Code to call usage_status again. After revocation the call returns authorization required.
3. Step 3: Clear Claude Code's stored credentials with claude mcp logout, and remove the local server entry when you no longer want Claude Code to offer Rivul MCP tools.

claude mcp logout rivul-atlas
claude mcp remove rivul-atlas

Troubleshooting

The browser says localhost refused to connect after consent. Anthropic's MCP guide says to paste the full callback URL from the browser's address bar into the URL prompt Claude Code shows. If the CLI still does not reconnect, remove the incomplete grant in Rivul MCP and rerun login. Claude uses a temporary localhost callback port; current Rivul OAuth accepts that standards-defined loopback behavior without relaxing non-loopback redirects.

The wrong workspace was approved. Disconnect the grant and sign in again against the intended workspace. Never paste a session cookie or your Google password into Claude Code, or store a complete token in a tracked project file.

A connection that worked stops working. Read usage_status, which never counts toward usage. A revoked key returns HTTP 401 Invalid Rivul Atlas key, while a rate limit asks the client to retry later.

• Anthropic Claude Code MCP documentation
• Model Context Protocol authorization specification
• Rivul MCP tool reference
• Rivul MCP overview
• Open Rivul MCP