> ## Documentation Index
> Fetch the complete documentation index at: https://docs.range.org/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Quickstart

> Connect Claude, Cursor, or any MCP-compatible AI client to Range in under 5 minutes.

## Prerequisites

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

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

## MCP endpoint

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

This endpoint speaks the [Model Context Protocol](https://modelcontextprotocol.io) 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.
* **Legacy/global API keys** can call every tool that isn't workspace-scoped (address intelligence, risk, network/token stats, explorer tools, and the global screening/plan catalogues).
* **Workspace-scoped API keys** (`<workspaceId>.<jwt>`) additionally unlock the workspace-scoped tools: accounts, balances, alerts, counterparties, transfer enrichment, and the v2 screening pipeline. Calling a workspace-scoped tool with a legacy key returns a clear error asking for a workspace-scoped key instead of silently returning empty data.
* A workspace member with the **READER** role has full access to every tool a workspace key can reach — the whole MCP surface is read-only, so no elevated role is required.
* 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.

### API key scopes

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

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

**For full MCP visibility, create the key with all three scopes enabled.** The MCP surface spans all three areas, and a key provisioned with every read scope keeps working as per-scope enforcement rolls out across tool categories. All scopes are read-only through the MCP — no scope grants write access.

See the [Tools Reference](/ai/tools-reference) for which tools are workspace-scoped.

***

## Connect your client

<Tabs>
  <Tab title="Claude Desktop">
    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`:

    ```json theme={null}
    {
      "mcpServers": {
        "range": {
          "type": "http",
          "url": "https://api.range.org/ai/mcp",
          "headers": {
            "Authorization": "Bearer your_api_key_here"
          }
        }
      }
    }
    ```

    Restart Claude Desktop. You should see "range" appear in the tools panel (hammer icon).
  </Tab>

  <Tab title="Claude.ai">
    In [Claude.ai](https://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_here`

    Save and refresh. Range tools will be available in any new conversation.
  </Tab>

  <Tab title="Cursor">
    Open Cursor settings (`Cmd/Ctrl + ,`) and navigate to **Features → MCP Servers**.

    Add a new server:

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

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

  <Tab title="Test with curl">
    The server is stateless: no session id is issued or required, and every
    request stands on its own. You can call any method directly.

    <Note>
      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.
    </Note>

    **List the available tools:**

    ```bash theme={null}
    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_here" \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```

    **Call a tool:**

    ```bash theme={null}
    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_here" \
      -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 74 tools.
  </Tab>
</Tabs>

***

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

***

## Next steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/ai/tools-reference">
    Browse all 74 tools with parameters and descriptions.
  </Card>

  <Card title="Investigation Playbook" icon="magnifying-glass" href="/ai/investigation-playbook">
    Learn the full step-by-step investigation workflow.
  </Card>
</CardGroup>