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

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

Available Resources

Available Prompts

Write Tools (requires read-write scope)

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.