Use HelpRange from Claude, Cursor and your AI agents

claude mcp add --transport http helprange https://www.helprange.com/mcp

{
  "mcpServers": {
    "helprange": {
      "url": "https://www.helprange.com/mcp"
    }
  }
}

code --add-mcp '{"name":"helprange","type":"http","url":"https://www.helprange.com/mcp"}'

{
  "servers": {
    "helprange": {
      "type": "http",
      "url": "https://www.helprange.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "helprange": {
      "url": "https://www.helprange.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "helprange": {
      "serverUrl": "https://www.helprange.com/mcp"
    }
  }
}

import { generateText, tool, stepCountIs } from 'ai';
import { z } from 'zod';

const HR = 'https://www.helprange.com/api/v2';
const headers = { Authorization: `Bearer ${process.env.HELPRANGE_API_KEY}` };

const listDocuments = tool({
  description: 'List HelpRange documents with views and downloads',
  inputSchema: z.object({}),
  execute: async () => (await fetch(`${HR}/documents`, { headers })).json(),
});

const createLink = tool({
  description: 'Create a tracked HelpRange share link for one person',
  inputSchema: z.object({ fileId: z.number(), label: z.string() }),
  execute: async ({ fileId, label }) =>
    (await fetch(`${HR}/files/${fileId}/links`, {
      method: 'POST',
      headers: { ...headers, 'Content-Type': 'application/json' },
      body: JSON.stringify({ label, require_email: true }),
    })).json(),
});

const { text } = await generateText({
  model, // any AI SDK model
  tools: { listDocuments, createLink },
  stopWhen: stepCountIs(5),
  prompt: 'Create a link to proposal.pdf for "ACME - Anna".',
});

import os
import requests
from langchain_core.tools import tool

HR = "https://www.helprange.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['HELPRANGE_API_KEY']}"}


@tool
def recent_views() -> list:
    """Who opened which HelpRange document recently (newest first)."""
    return requests.get(f"{HR}/views", headers=HEADERS, timeout=30).json()


@tool
def create_link(file_id: int, label: str) -> dict:
    """Create a tracked HelpRange share link for one person; the viewer must enter their e-mail."""
    r = requests.post(f"{HR}/files/{file_id}/links", headers=HEADERS, timeout=30,
                      json={"label": label, "require_email": True})
    return r.json()


llm_with_tools = llm.bind_tools([recent_views, create_link])  # llm: any chat model with tool calling

import os
import requests
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.tools import FunctionTool

HR = "https://www.helprange.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['HELPRANGE_API_KEY']}"}


def document_stats(document_id: int) -> dict:
    """Views, downloads and seconds per page of one HelpRange document."""
    return requests.get(f"{HR}/documents/{document_id}", headers=HEADERS, timeout=30).json()


async def main(llm):  # llm: any LlamaIndex LLM with function calling
    agent = FunctionAgent(tools=[FunctionTool.from_defaults(fn=document_stats)], llm=llm)
    return await agent.run("How long did people read page 3 of document 250?")

import os
import requests
from agents import Agent, Runner, function_tool

HR = "https://www.helprange.com/api/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['HELPRANGE_API_KEY']}"}


@function_tool
def invite_guest(data_room_id: int, email: str) -> dict:
    """Invite a guest to a HelpRange data room (they get the room's invitation e-mail)."""
    r = requests.post(f"{HR}/data-rooms/{data_room_id}/guests", headers=HEADERS, timeout=30, json={"email": email})
    return r.json()


agent = Agent(name="Deal assistant", instructions="Manage HelpRange data rooms.", tools=[invite_guest])
result = Runner.run_sync(agent, "Invite jane@example.com to data room 10.")
print(result.final_output)

## Using HelpRange in this project

HelpRange (secure document sharing, tracked links, virtual data rooms) is called through its REST API.

- Base URL: `https://www.helprange.com/api/v2` (JSON in, JSON out; uploads also as multipart/form-data).
- Auth: `Authorization: Bearer $HELPRANGE_API_KEY` – a team API key from HelpRange Settings → API keys. Never commit
  the key or send it from browser code; read it from the environment.
- Test mode: keys starting with `hr_test_` work on a sandbox with sample data – no e-mail is sent, only addresses at
  example.com / example.org / *.test are accepted, nothing touches live data. Use a test key in development and CI;
  responses carry `"livemode": false`.
- Scopes: each key has scopes (`documents:read`, `documents:write`, `links:read`, `links:write`, `rooms:read`,
  `rooms:write`, `analytics:read`, `team:read`). 403 `insufficient_scope` names the missing one in `required_scope`.
- Full reference (Markdown, for LLMs): https://www.helprange.com/developers/llms-full.txt · OpenAPI 3.1: https://www.helprange.com/developers/openapi.json
  · Human docs: https://www.helprange.com/developers/api

Key endpoints:
- `GET /api/v2/me` – Who is connected
- `GET /api/v2/folders` – List folders
- `GET /api/v2/documents` – List documents
- `POST /api/v2/files` – Upload a file
- `POST /api/v2/files/{file_id}/links` – Create a share link
- `GET /api/v2/documents/{file_id}/links` – List share links of a document
- `GET /api/v2/documents/{file_id}` – Document statistics
- `GET /api/v2/views` – Recent document views
- `GET /api/v2/data-rooms` – List data rooms
- `GET /api/v2/data-rooms/{data_room_id}` – Data room details
- `POST /api/v2/data-rooms/{data_room_id}/documents` – Add documents to a data room
- `POST /api/v2/data-rooms/{data_room_id}/guests` – Invite a guest
- `POST /api/v2/signature-requests` – Send a document for e-signature
- `POST /api/v2/offers` – Create an offer
- `GET /api/v2/activity` – Team activity

Errors: JSON `{"error": "…"}`, some with `code`. 400 invalid input (the message names the field), 401 bad / revoked /
expired key, 402 plan without API access, 403 missing scope, 404 not found or not yours, 409 / 423 frozen data room,
413 file too large, 429 rate limit – wait `Retry-After` seconds (also `retry_after` in the body).

Retries / idempotency: there is no Idempotency-Key header. GETs are safe to retry. Give every share link a unique
`label` (per document): retrying a create with the same label answers 400 instead of making a duplicate – then list
the document's links (`GET /api/v2/documents/{file_id}/links`). Inviting someone who is already a guest answers 200
with `already_a_guest: true`. Back off on 429 and 5xx.

Rules worth knowing: `expires_on` must be today or later (`YYYY-MM-DD`); `views_limit` 0 or null = no limit;
booleans accept true/false, 1/0 or "true"/"false"; a passcode of only spaces = no passcode. The API never e-mails
share links – send the returned `url` yourself. Usage limits per team: 3,600 requests an hour (120 a minute), 300
writes an hour, 2,000 new links and 1,000 guests a day.

Webhooks (set up in Settings → Integrations, not through the API): verify `HelpRange-Signature: t=…,v1=…` =
HMAC-SHA256(secret, "<t>.<raw body>"), reject timestamps older than 5 minutes, deduplicate on the event `id`, answer
2xx fast. Docs: https://www.helprange.com/developers/webhooks