AI Quickstart

Prerequisites

A Range API key, get one at app.range.org/keys
An MCP-compatible AI client (Claude Desktop, Claude.ai, Cursor, or any OpenAI-compatible tool)

You use the same API key you already have. No new credentials, no separate signup.

MCP endpoint

https://api.range.org/ai/mcp

This endpoint speaks the Model Context Protocol over Streamable HTTP. Every call is authenticated with your existing API key.

Key types and workspace access

Authorization: Bearer <api_key> is the recommended way to authenticate. An x-api-key: <api_key> header is also accepted as an alternative.
The server is stateless: no session id is issued or required. Every request is independent and authenticated on its own, so connections are unaffected by server maintenance or restarts.

The server accepts three types of key. What a key can call depends on whether it carries a workspace and a workspace member:

Key type	Format	Workspace member and role	What it can call
Managed workspace key	`<workspaceId>.<key>`	None	Every read tool, including the workspace-scoped tools. Not the four mutating tools or `get_current_member`.
Workspace-user key	`<workspaceId>.<jwt>`	One member, with a role (READER, EDITOR, or ADMIN)	Every read tool, including the workspace-scoped tools. The four mutating tools require EDITOR or higher.
Legacy/global key	No workspace prefix	None	Only the tools that are not workspace-scoped (address intelligence, risk, network/token stats, explorer tools, and the global screening/plan catalogues).

The API keys you create in the dashboard at app.range.org/keys are managed workspace keys. They are scoped to your workspace but carry no member and no role. They can call every read tool, but not the four mutating tools (add_accounts, create_counterparty, add_counterparty_addresses, create_alert_rule) or get_current_member. A mutating tool called with a managed key returns an error instead of making a change.
A workspace-user key is the <workspaceId>.<jwt> credential a signed-in Range app session presents. It identifies one workspace member and that member’s role. The dashboard’s API keys page does not issue this type of key.
The workspace-scoped tools cover accounts, balances, alerts, counterparties, transfer enrichment, and the v2 screening pipeline. Calling one with a legacy key returns a clear error asking for a workspace-scoped key instead of silently returning empty data.

API key scopes

When creating an API key you choose which APIs it can read:

Risk API covers risk scoring, sanctions/OFAC checks, and the screening pipeline (risk scores, screening evidence and history).
Data API covers blockchain data reads: addresses, transactions, transfers, tokens, and network/explorer analytics.
Platform API covers your workspace’s own product data: accounts, balances, groups, alert rules and events, counterparties, and transfer notes.

A managed key needs the Data API scope to connect. The MCP endpoint checks the key’s Data API scope on every request and refuses a managed key that does not have it enabled. The tools span all three areas, so enable all three scopes when you create a key for MCP. Scopes do not grant write access: the mutating tools require a workspace-user key whose member has EDITOR role or higher. See the Tools Reference for which tools are workspace-scoped or mutating.

Connect your client

Claude Desktop
Claude.ai
Cursor
Test with curl

Open your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Range server under mcpServers:

{
  "mcpServers": {
    "range": {
      "type": "http",
      "url": "https://api.range.org/ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Restart Claude Desktop. You should see “range” appear in the tools panel (hammer icon).

In Claude.ai, go to Settings → Integrations → Add MCP Server:

Name: Range
URL: https://api.range.org/ai/mcp
Authentication: Custom header
- Header: Authorization
- Value: Bearer YOUR_API_KEY

Save and refresh. Range tools will be available in any new conversation.

Open Cursor settings (Cmd/Ctrl + ,) and navigate to Features → MCP Servers.Add a new server:

{
  "range": {
    "type": "http",
    "url": "https://api.range.org/ai/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY",
      "Accept": "application/json, text/event-stream"
    }
  }
}

Or add it to your .cursor/mcp.json file in any project directory to scope it per-project.

The server is stateless: no session id is issued or required, and every request stands on its own. You can call any method directly.

MCP clients (Claude Desktop, Claude.ai, Cursor, etc.) still send an initialize handshake automatically when they connect. That’s part of the protocol and works as normal. Statelessness just means you don’t have to manage a session id yourself when testing with curl, Postman, or a custom client.

List the available tools:

curl -X POST https://api.range.org/ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Call a tool:

curl -X POST https://api.range.org/ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"check_sanctions","arguments":{"address":"0x7F367cC41522cE07553e823bf3be79A889DEbe1B"}}}'

A successful tools/list response returns a JSON array of 85 tools.

Your first investigation

Once connected, paste this prompt into your AI client:

Investigate this wallet and tell me if I should be concerned about it:
5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1

Check its risk score, see if it's sanctioned, find its top counterparties,
and summarize what kind of entity this appears to be.

The AI will call get_address_risk, check_sanctions, get_address_connections, and get_address_info autonomously and return a structured summary.

Getting Started

MCP Tools

Prerequisites

MCP endpoint

Key types and workspace access

API key scopes

Connect your client

Your first investigation

Next steps

Tools Reference

Investigation Playbook

​Prerequisites

​MCP endpoint

​Key types and workspace access

​API key scopes

​Connect your client

​Your first investigation

​Next steps

Tools Reference

Investigation Playbook

Prerequisites

MCP endpoint

Key types and workspace access

API key scopes

Connect your client

Your first investigation

Next steps