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

# MCP Server

> Connect AI assistants like Claude to your rewards data via the Model Context Protocol.

The MCP server lets AI clients query and manage your rewards data in natural language. It exposes the same read/write operations as the REST API as callable tools.

**Endpoint:** `https://mcp.rewards.so`

***

## Connecting Claude

### Claude.ai + Claude Code — simplest

Go to **claude.ai → Customize → Connectors** and click **Add connector**. Fill in:

| Field | Value                    |
| ----- | ------------------------ |
| Name  | `Rewards`                |
| URL   | `https://mcp.rewards.so` |

Save. An OAuth popup will ask you to authorize your Rewards account. Once approved, the connector is available in all Claude.ai conversations.

**Claude Code bonus:** if you're signed into Claude Code with the same account, connectors you've added on claude.ai automatically appear in Claude Code — no extra setup needed.

***

### Claude Code (CLI, alternative)

If you prefer to add it directly from the terminal:

```bash theme={null}
claude mcp add --transport http https://mcp.rewards.so
```

The OAuth flow opens in your browser. If the auto-redirect fails, copy the callback URL from your browser's address bar and paste it back into the terminal.

***

### Claude Desktop

Claude Desktop uses a separate config file — it does not sync with your claude.ai account. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

```json theme={null}
{
  "mcpServers": {
    "rewards": {
      "url": "https://mcp.rewards.so"
    }
  }
}
```

Restart Claude Desktop. A browser window will open to authorize access on first launch.

***

All clients support OAuth natively via [RFC 7591 Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) — no pre-configured credentials needed.

***

## Connecting other clients (Cursor, etc.)

Clients that don't support OAuth can authenticate with an API key. Generate one in **Account → Integration**, then pass it as a Bearer token:

```json theme={null}
{
  "rewards": {
    "url": "https://mcp.rewards.so",
    "headers": {
      "Authorization": "Bearer rw_yourkey"
    }
  }
}
```

Keys with `read` permission enable read-only tools; keys with `all` permission enable read and write tools.

If your key has access to multiple point systems, add:

```
X-Point-System-Id: <your-point-system-uuid>
```

***

## Available tools

Every tool takes an optional `pointSystemId`, required only if your key covers more than one point system.

### Read tools

| Tool                      | Description                                                                                                                         |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `list_point_systems`      | The point systems this key can reach                                                                                                |
| `get_point_system`        | Metadata and stats (total wallets, total points, ban count)                                                                         |
| `get_leaderboard`         | Top wallets ranked by points. Params: `limit` (1–200), `page`                                                                       |
| `get_wallet`              | Points, rank, events, and blacklist status for an address or ENS name                                                               |
| `search_wallets`          | Search wallets by address substring. Params: `query`, `limit`                                                                       |
| `list_wallets`            | Page through every wallet with its points and blacklist status. Params: `page`, `limit`, `search`, `sort`                           |
| `get_wallet_events`       | Full point history for a wallet                                                                                                     |
| `get_blacklisted_wallets` | List of banned wallets with reasons                                                                                                 |
| `get_analytics`           | Wallets, points and events over a window, each compared with the window before it. Param: `days`                                    |
| `get_activity_log`        | Who did what, 30-day retention. Params: `page`, `limit`, `actionType`                                                               |
| `list_point_triggers`     | Point triggers: a trigger key your app fires, worth a fixed number of points                                                        |
| `list_reward_automations` | Reward automations: conditions that queue wallets into a rolling draft reward                                                       |
| `get_automation_options`  | The views, levels and event types you can build automation conditions from                                                          |
| `list_rewards`            | Reward campaigns with their status and claim counts                                                                                 |
| `get_reward`              | One campaign in detail, including claimed vs unclaimed                                                                              |
| `list_views`              | Saved leaderboard filters, referenced by `view_rank` conditions                                                                     |
| `list_badges`             | Badge families and their tiers (progression levels), with each tier's conditions. The "Levels" family is the migrated legacy levels |
| `search_docs`             | Search the Rewards documentation (docs.rewards.so). Params: `query`, `limit`                                                        |
| `get_doc`                 | Read one documentation page in full. Param: `slug`                                                                                  |

### Write tools

Write tools require an `all` API key or OAuth with write scope.

| Tool                                                                  | Description                                                                                     |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `add_points`                                                          | Add points to a wallet (creates it if new). Params: `address`, `amount`, `eventType` (optional) |
| `add_points_bulk`                                                     | Same thing for many wallets in one call. Param: `entries`                                       |
| `ban_wallet`                                                          | Blacklist a wallet. Params: `address`, `reason`                                                 |
| `unban_wallet`                                                        | Remove a wallet from the blacklist. Params: `address`                                           |
| `create_point_trigger`                                                | Create a point trigger. Params: `name`, `triggerKey`, `pointsAmount`                            |
| `update_point_trigger`                                                | Rename a trigger or change what it is worth                                                     |
| `toggle_point_trigger`                                                | Activate or pause a point trigger                                                               |
| `delete_point_trigger`                                                | Delete a point trigger                                                                          |
| `create_reward_automation`                                            | Create a reward automation from conditions and a reward template                                |
| `toggle_reward_automation`                                            | Activate or pause a reward automation                                                           |
| `delete_reward_automation`                                            | Delete a reward automation                                                                      |
| `create_reward_draft`                                                 | Draft a reward campaign                                                                         |
| `update_reward_draft`                                                 | Edit a campaign that is still a draft                                                           |
| `delete_reward_draft`                                                 | Delete a campaign that is still a draft                                                         |
| `create_view` / `update_view` / `delete_view`                         | Manage saved leaderboard filters                                                                |
| `create_badge_family` / `update_badge_family` / `delete_badge_family` | Manage badge families                                                                           |
| `create_badge_tier` / `update_badge_tier` / `delete_badge_tier`       | Manage tiers (progression levels) and their conditions                                          |

All tools accept ENS names (`.eth`) in addition to `0x` addresses.

### What the MCP will never do

Publishing a campaign on-chain, cancelling one, and upgrading the contract all need a wallet signature, so they only exist in the dashboard. The MCP stops at the draft: an agent can prepare a campaign down to the last wallet, but you are the one who signs it. `update_reward_draft` and `delete_reward_draft` refuse anything that is no longer a draft or already has an on-chain id.

***

## Example prompts

```
"Analyse le top 50 du leaderboard et identifie les wallets qui semblent farmer"
"Ban tous les wallets avec moins de 3 events distincts et plus de 10 000 points"
"Montre-moi l'historique complet de 0x1234..."
"Ajoute 500 points à vitalik.eth pour l'event discord_launch"
"Quels wallets ont été bannis cette semaine ?"
"Compare les 30 derniers jours aux 30 précédents"
"Crée un trigger connect_telegram à 50 points"
"Prépare un draft de campagne pour le top 100, 0.001 SOMI par wallet"
"Qui a modifié les automations ce mois-ci ?"
```

***

## Audit trail

Every write is recorded in the activity log with the API key or OAuth client ID. All MCP actions are fully auditable from the dashboard, or through `get_activity_log`.