Rockhopper 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 18+
• A Rockhopper account with at least one enrolled file
• (Optional) A Personal Access Token — only required for headless / CI / scripted setups

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 Desktop / Claude Code

Add to your MCP config (~/.claude/mcp.json or Claude Desktop settings):

{
  "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

Variable	Required	Default	Description
ROCKHOPPER_TOKEN	No	—	Personal Access Token (starts with rh_pat_). When unset, OAuth device-grant flow runs on first launch.
ROCKHOPPER_API_URL	No	https://api.rockhopper.co	Rockhopper API base URL
ROCKHOPPER_MCP_LOG_DIR	No	~/.rockhopper/mcp-server/	Directory for the local diagnostic logfile (see below).
ROCKHOPPER_MCP_LOG_DISABLE	No	—	Set truthy (1 / true) to disable local diagnostic logging entirely.
ROCKHOPPER_MCP_LOG_LEVEL	No	info	Diagnostic log level (fatal / error / warn / info / debug / trace / silent).

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

Tool	Description
list_files	List enrolled Excel files with optional search filter
get_file_versions	Get version history for a specific file
get_file_comments	Get comments and threaded discussions on a file
get_reviews	Get review requests for a version or file
get_cell_history	Get change history for a specific cell across versions
search_files	Search enrolled files by name
get_unattributed_changes	Get pending cell changes not yet committed to a version

Available Resources

Resource	URI	Description
Enrolled Files	rockhopper://files	All enrolled files in workspace
File Detail	rockhopper://files/{fileMsId}	Details for a specific file
File Versions	rockhopper://files/{fileMsId}/versions	Version history for a file
Version Detail	rockhopper://versions/{versionId}	Single version details
File Comments	rockhopper://files/{fileMsId}/comments	Comments on a file
Version Reviews	rockhopper://versions/{versionId}/reviews	Reviews for a version
Review Detail	rockhopper://reviews/{reviewId}	Single review details
Team Detail	rockhopper://teams/{teamId}	Team details with members
Unattributed Changes	rockhopper://files/{fileMsId}/changes	Pending changes

Available Prompts

Prompt	Description
summarize-file-changes	Summarize recent version changes and unattributed edits for a file
pending-reviews	Show all pending review requests for the latest version of a file
unresolved-comments	List all unresolved comments on a file for follow-up
file-overview	Comprehensive overview: versions, comments, reviews, and changes

Write Tools (requires read-write scope)

Tool	Description
create_version	Commit uncommitted changes as a new semver version (major/minor/patch)
discard_changes	Discard all uncommitted changes, revert to latest committed version
add_comment	Add a comment to an enrolled file (optionally at a cell)
reply_to_comment	Reply to an existing comment thread
resolve_comment	Mark a comment as resolved (author only)
create_review_request	Request a review on a file version
approve_review	Approve a review request (assigned reviewer only)
cancel_review	Cancel a pending review request (requester only)
update_file_description	Update the display name of an enrolled file

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.