Rockhopper MCP Server

MCP (Model Context Protocol) server for Rockhopper. Lets AI tools like Claude, Cursor, and Copilot interact with your Rockhopper workspace — enrolled files, version history, reviews, comments, and cell-level change tracking.

Prerequisites

• Node.js 20+

• A Rockhopper account with at least one enrolled file

• (Optional) A Personal Access Token — only required for headless / CI / scripted setups

Related MCP server: Dovetail MCP Server

Authentication

The server supports two auth modes. OAuth (recommended) is the default — no token to copy and paste. PAT stays available for headless scenarios.

OAuth (recommended)

On first launch, the server prints a short verification code to stderr and a URL to visit. Sign in once in your browser — the resulting bearer token is stored in your OS keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux). Subsequent launches pick the token up silently.

Nothing to configure — just launch the server with no ROCKHOPPER_TOKEN set:

npx @rockhopper-co/mcp-server

You'll see (on stderr):

Rockhopper — sign in to authorize this MCP client.
Open: https://app.rockhopper.co/device?user_code=ABCD2345
(or visit https://app.rockhopper.co/device and enter code: ABCD2345)

Tokens default to a 60-minute lifetime. When yours expires, the next launch silently re-runs the device flow.

Linux: requires libsecret to be installed (apt-get install libsecret-1-dev on Debian/Ubuntu, dnf install libsecret on Fedora). If unavailable, fall back to the PAT path below.

Personal Access Token (headless / CI)

For non-interactive setups, generate a PAT in the Rockhopper web app under Settings > Personal Access Tokens (read-only or read-write scope) and set it as ROCKHOPPER_TOKEN. PATs take precedence over OAuth — if ROCKHOPPER_TOKEN is set, the device-grant flow is skipped.

Setup

1. Install

npm install -g @rockhopper-co/mcp-server

Or run directly with npx:

npx @rockhopper-co/mcp-server

2. Configure your AI tool

Claude Code

Run once:

claude mcp add --env ROCKHOPPER_API_URL=https://api.rockhopper.co --transport stdio rockhopper -- npx -y @rockhopper-co/mcp-server

Or add the JSON block from the Claude Desktop section below to .mcp.json at your project root. Claude Code keeps servers added with claude mcp add in ~/.claude.json (Claude Code MCP docs).

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "rockhopper": {
      "command": "npx",
      "args": ["-y", "@rockhopper-co/mcp-server"],
      "env": {
        "ROCKHOPPER_API_URL": "https://api.rockhopper.co"
      }
    }
  }
}

Leave ROCKHOPPER_TOKEN out to use OAuth (recommended). Set it if you want PAT auth instead.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "rockhopper": {
      "command": "npx",
      "args": ["-y", "@rockhopper-co/mcp-server"],
      "env": {
        "ROCKHOPPER_API_URL": "https://api.rockhopper.co"
      }
    }
  }
}

Environment Variables

Diagnostic Logging

The server writes a local diagnostic logfile to ~/.rockhopper/mcp-server/ (rotated, size-capped at ~5 MB × 5 files, named mcp-server.<n>.log). It records request latency and the client-side failures the API never sees — network-unreachable errors, local auth rejections, response schema drift, and uncaught crashes — so you can hand the file to Rockhopper support when something misbehaves.

• Local only. Nothing is transmitted anywhere — the file stays on your machine. There is no remote telemetry.

• Redacted. Tokens, the Authorization header, request/response bodies, tool arguments, and cell data are never written. Lines carry only event name, HTTP method, URL pathname (no query string), status code, duration, tool name, a correlation id, and error type/message.

• Configurable. Point it elsewhere with ROCKHOPPER_MCP_LOG_DIR, change verbosity with ROCKHOPPER_MCP_LOG_LEVEL, or turn it off with ROCKHOPPER_MCP_LOG_DISABLE=1. If the file can't be opened, logging silently disables — it never interferes with the server.

Postman

A starter Postman collection + environment files are available in postman/ for gateway smoke testing (/healthz, /mcp initialize, /mcp tools/list) across local/dev/staging/production.

Regenerate artifacts with:

npm run generate:postman

Available Tools

Account Link Tools

Available Resources

Available Prompts

Write Tools (each requires its write capability)

Identifiers

Users and teams are named by a uuid (id) — for example 0198f3a1-2b4c-7d8e-9f01-23456789abcd. This is the identifier to send as a reviewerIds entry on create_review_request, and as {teamId} in rockhopper://teams/{teamId}. Read it from the team resource, where every record carries both an id (uuid) and an internalId (number).

The legacy numeric internalId is also accepted for users and teams, and the two spellings can be mixed in one reviewerIds array — nothing you have written today stops working. It is accepted until 2027-09-14 and removed after, so migrate to the uuid before then.

Everything else keeps its existing type: fileMsId is a string, and version and comment ids stay numeric.

Development

# Install dependencies
npm install

# Run in dev mode (auto-restart on changes)
npm run dev

# Build
npm run build

# Run tests
npm test

# Type check
npm run typecheck

Security

• Tokens are scoped to the creating user — the MCP server can only access data the user has permission to see

• read-only tokens cannot perform write operations (comments, reviews)

• All API calls go through Rockhopper's existing authorization guards

• Tokens can be revoked instantly from the Settings page

• The MCP server runs locally and communicates with the API over HTTPS

Architecture

AI Tool (Claude/Cursor) <--stdio--> mcp-server <--HTTPS--> Rockhopper API <--> PostgreSQL

The MCP server is a thin adapter. It translates MCP tool/resource requests into Rockhopper REST API calls, authenticated with the user's PAT. All authorization is enforced server-side — the MCP server has no direct database access.