> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-operations-on-the-users.md).

# MCP - operations on the users

These MCP operations read or change **one player**. Each one does what a button on the player's profile in the Back-Office does: the same checks apply, and every change is written to the player's history.

## How to call them

Run the two read operations, `user_get_state` and `user_get_missions`, with `read_operation`. It never changes anything, so an AI assistant can run it without asking. Run every other operation with `exec_operation`. Put the operation's fields in `params`; `dry_run` and `label_id` go next to `params`, not inside it. `dry_run` is optional: without it, the operation runs.

```json
// request: the arguments of exec_operation
{
  "operation": "user_adjust_points",
  "params": { "user_id": 1000021, "points": -50, "affects_leaderboard": false },
  "dry_run": true
}
// response
{
  "type": "ok",
  "data": {
    "dry_run": true,
    "user_id": 1000021,
    "user_ext_id": "p1",
    "action": "Adjust the player's points by -50",
    "executed": false
  }
}
```

The examples on this page show the arguments of the tool and the JSON answer (`x-mcp-mode: json`). For the full HTTP request, see [MCP - Connection and security](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connection-and-security.md). To act on several players in one request, the `batch` tool runs up to 20 calls in order; each call is checked as if it were sent alone.

**Choosing the player.** Every operation takes exactly one of these two fields (`user_start_campaign` can take a segment instead). The parameter tables below do not repeat them.

| Parameter     | Meaning                                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `user_ext_id` | The player's id in your own system. On a multi-brand account, with or without the brand prefix that the Back-Office shows. |
| `user_id`     | The player's Smartico id. It is never ambiguous, so use it when you have it.                                               |

The player must belong to the label of the call. If no player matches, or several brands have the same `user_ext_id`, the answer is a question and nothing changes.

**Answers.** Most changes answer `"type": "ok"` with the player, the `action` in words and `"executed": true`, and `result`, the platform's own message. Some changes (opt-outs, flags, markers, points) reach the profile only after a few minutes; their `result` says so. Each operation below shows its answer. With the optional `dry_run: true`, the same checks run and the answer names the player and the `action` in words, with `"executed": false`; nothing is done. If a check fails (for example, the mission is not unlocked), the answer is `"type": "question"` with the reason in `text`, and nothing is sent. If the platform refuses the change, the answer is `"type": "error"`.

**Comment.** Operations that list `comment` store it with the change in the player's history, as "MCP: " and your text (at most 1,000 characters). Without a comment, the history shows "MCP". So you can always tell an MCP change from a click in the Back-Office.

{% hint style="info" %}
An access profile can allow only some operations. A refused call names the profile and lists what it allows. See [MCP - Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md).
{% endhint %}

## Reading a player

### `user_get_state`

The player's profile overview, as the Back-Office shows it: ids, brand, username, level counters and the value of each active property. The e-mail and phone number are masked. Properties that are restricted for your Back-Office user are left out.

| Parameter    | Meaning                                                                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Optional. A list of 1 to 200 property names, to get only these properties. Find names with `entity_list` on `property`. A name that is not found is listed in `not_found`. |

```json
// request: the arguments of read_operation
{
  "operation": "user_get_state",
  "params": { "user_id": 1000021, "properties": ["core_tags", "acc_last_login_date"] }
}
// response
{
  "type": "ok",
  "data": {
    "player": {
      "user_id": "1000021",
      "user_ext_id": "p1",
      "user_ext_id_clean": "p1",
      "crm_brand_id": 12,
      "crm_brand_name": "Main brand",
      "public_username": "p1",
      "avatar_id": null,
      "level_counter_1": null,
      "level_counter_2": null
    },
    "properties": [
      { "name": "core_tags", "ui_name": "Core: user markers", "value": null, "type": "STRINGS_ARRAY", "product": "Core" }
    ],
    "not_found": ["acc_last_login_date"]
  }
}
```

### `user_get_missions`

The player's missions now, as on the **Missions** tab of the profile: every unlocked mission or badge (`type` says which), completed or in progress, with its progress, its tasks, and whether its prize waits for a claim. Run it before `user_complete_mission` or `user_claim_mission_reward`.

No parameters besides the player.

```json
// request: the arguments of read_operation
{ "operation": "user_get_missions", "params": { "user_ext_id": "p1" } }
// response
{
  "type": "ok",
  "data": {
    "player": { "user_id": 1000021, "user_ext_id": "p1" },
    "missions": [
      {
        "mission_id": 73854,
        "name": "Deposit 3 times",
        "type": "mission",
        "completed": false,
        "progress": 66,
        "unlock_date": 1760000000000,
        "complete_date": null,
        "completion_id": null,
        "requires_prize_claim": false,
        "prize_claimed": false,
        "points_reward": 100,
        "tasks": [
          { "task_id": 1, "name": "Make a deposit", "completed": false, "progress": 66, "executed_count": 2 }
        ]
      }
    ],
    "completed": 0,
    "in_progress": 1
  }
}
```

## Missions, points and levels

### `user_complete_mission`

Completes a mission for the player, and the player gets its rewards. The mission must be unlocked for the player and not completed yet (see `user_get_missions`).

| Parameter    | Meaning                                                          |
| ------------ | ---------------------------------------------------------------- |
| `mission_id` | Required. The mission. Find ids with `entity_list` on `mission`. |
| `comment`    | Optional. Stored in the player's history.                        |

```json
// request
{ "operation": "user_complete_mission", "params": { "user_ext_id": "p1", "mission_id": 73854, "comment": "asked by support" } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Complete mission #73854 for the player (the player gets its rewards)", "executed": true, "result": "Mission is completed" } }
```

### `user_claim_mission_reward`

Claims the prize of a completed mission whose prize waits for a manual claim. The prize must not be claimed yet, and the claim time must not be over. If the mission has no claim time set, the player can claim for 180 days after completing it.

| Parameter    | Meaning                                   |
| ------------ | ----------------------------------------- |
| `mission_id` | Required. The completed mission.          |
| `comment`    | Optional. Stored in the player's history. |

```json
// request
{ "operation": "user_claim_mission_reward", "params": { "user_ext_id": "p1", "mission_id": 73854 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Claim the prize of completed mission #73854 for the player", "executed": true, "result": "Mission is claimed, note that it may take some time for the changes to be reflected across the system" } }
```

### `user_give_mission`

Gives (unlocks) a mission for the player. Only a mission that is given manually can be given.

| Parameter    | Meaning                                                                                                                                                                                                                                                                                                                           |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mission_id` | Required. A mission that is given manually.                                                                                                                                                                                                                                                                                       |
| `reset_mode` | Optional. What happens to the progress if the player already has the mission: `keep` (default) keeps it; `reset_if_not_completed` resets it unless the mission is completed; `restart_if_completed` resets the progress and starts the mission again if it was completed; `reset` resets the progress of a mission already given. |
| `comment`    | Optional. Stored in the player's history.                                                                                                                                                                                                                                                                                         |

```json
// request
{ "operation": "user_give_mission", "params": { "user_id": 1000021, "mission_id": 73860, "reset_mode": "reset_if_not_completed" } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Give mission #73860 to the player (reset mode ResetIfNotCompleted)", "executed": true, "result": "Mission is given for user" } }
```

### `user_adjust_points`

Adds or takes away points, gems or diamonds. Send one of the three, or all three in one call; two of them need two calls. Gems and diamonds need the Diamonds and Gems product on the account.

| Parameter             | Meaning                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `points`              | A whole number other than 0. A negative number takes points away.                                             |
| `gems`                | The same, for gems.                                                                                           |
| `diamonds`            | The same, for diamonds.                                                                                       |
| `affects_balance`     | Optional, `true` by default. The points count toward the player's points balance.                             |
| `affects_level`       | Optional, `true` by default. The points count toward the player's level.                                      |
| `affects_leaderboard` | Optional, `true` by default. The points count toward the leaderboard. At least one of the three stays `true`. |
| `comment`             | Optional. Stored in the player's history.                                                                     |

```json
// request
{ "operation": "user_adjust_points", "params": { "user_id": 1000021, "points": -50, "affects_leaderboard": false } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Adjust the player's points by -50", "executed": true, "result": "Points are adjusted, please note it may take some time for the changes to be reflected across the system" } }
```

### `user_change_level`

Moves the player to a level. It works only on accounts where levels are changed by hand, and only to an active level.

| Parameter  | Meaning                                                            |
| ---------- | ------------------------------------------------------------------ |
| `level_id` | Required. An active level. Find ids with `entity_list` on `level`. |
| `comment`  | Optional. Stored in the player's history.                          |

```json
// request
{ "operation": "user_change_level", "params": { "user_id": 1000021, "level_id": 512 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Move the player to level #512", "executed": true, "result": "Level is changed" } }
```

## Bonuses, mini-games and raffles

### `user_give_bonus`

Gives the player a bonus from an enabled bonus template. Because a bonus has a value, the call runs only with `confirm: true`; without it the answer is a question that says what would be given. `dry_run: true` works without `confirm`. Which fields the template needs depends on its bonus type.

| Parameter              | Meaning                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bonus_template_id`    | Required. An enabled bonus template. Find ids with `entity_list` on `bonus_template`.                                                                 |
| `bonus_amount`         | Required when the template needs an amount: more than 0 and not above the template's limit per issue. Leave it out when the template takes no amount. |
| `bonus_cost_value`     | Optional, only for a template that takes an amount: the bonus's cost value.                                                                           |
| `ui_amount`            | Optional. The amount as text, as the player sees it.                                                                                                  |
| `coupon_code`          | Required when the template needs a coupon; leave it out otherwise.                                                                                    |
| `redeem_automatically` | Optional, only for a template that offers the choice. `false` by default there; other templates are always redeemed automatically.                    |
| `ignore_bonus_cap`     | Optional, `false` by default. `true` gives the bonus even when the bonus cap is reached.                                                              |
| `comment`              | Optional. Stored in the player's history.                                                                                                             |
| `confirm`              | Required to give the bonus: `true`.                                                                                                                   |

```json
// request
{ "operation": "user_give_bonus", "params": { "user_id": 1000021, "bonus_template_id": 9021, "bonus_amount": 10, "confirm": true } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Give bonus template #9021 to the player (amount 10)", "executed": true, "result": "Bonus is given" } }
```

### `user_give_minigame_attempts`

Gives attempts of an active mini-game that is played with spin attempts. For a prize drop, use `user_give_prize_drop`.

| Parameter             | Meaning                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `minigame_id`         | Required. An active mini-game played with spin attempts. Find ids with `entity_list` on `minigame`.                      |
| `attempts`            | Optional. From 1 (default) to 1,000.                                                                                     |
| `show_game`           | Optional, `true` by default: the game opens for the player at once.                                                      |
| `delivery_timeout_ms` | Optional. How long the delivery waits for a player who is offline, in milliseconds: one day by default, at most 30 days. |
| `comment`             | Optional. Stored in the player's history.                                                                                |

```json
// request
{ "operation": "user_give_minigame_attempts", "params": { "user_id": 1000021, "minigame_id": 4410, "attempts": 3 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Give 3 attempt(s) of mini-game #4410 to the player and show the game", "executed": true, "result": "Spin attempts were issued" } }
```

### `user_give_prize_drop`

Sends an active prize drop to the player.

| Parameter             | Meaning                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| `minigame_id`         | Required. An active mini-game of the prize drop type.                                |
| `delivery_timeout_ms` | Optional. As for `user_give_minigame_attempts`: one day by default, at most 30 days. |
| `comment`             | Optional. Stored in the player's history.                                            |

```json
// request
{ "operation": "user_give_prize_drop", "params": { "user_id": 1000021, "minigame_id": 4415 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Send prize drop #4415 to the player", "executed": true, "result": "Prize Drop was sent" } }
```

### `user_give_raffle_tickets`

Gives tickets of an Active raffle. A draft raffle is refused: the platform answers "Raffle is not active".

| Parameter   | Meaning                                                              |
| ----------- | -------------------------------------------------------------------- |
| `raffle_id` | Required. An Active raffle. Find ids with `entity_list` on `raffle`. |
| `tickets`   | Optional. From 1 (default) to 1,000.                                 |
| `comment`   | Optional. Stored in the player's history.                            |

```json
// request
{ "operation": "user_give_raffle_tickets", "params": { "user_id": 1000021, "raffle_id": 230, "tickets": 5 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Give 5 ticket(s) of raffle #230 to the player", "executed": true, "result": "Raffle tickets were issued" } }
```

## Messages, forms and campaigns

### `user_set_channel_opt_out`

Opts the player out of Smartico messages on one channel, or back in. `ivr` works only on accounts that send IVR messages.

{% hint style="warning" %}
`user_set_channel_opt_out` still works in this release, but it will be removed in a later one. Use [`user_set_state`](#user_set_state) with `core_is_email_disabled`, `core_is_sms_disabled`, `core_is_push_disabled`, `core_is_ivr_disabled` or `core_is_whatsapp_disabled`.
{% endhint %}

| Parameter   | Meaning                                                                |
| ----------- | ---------------------------------------------------------------------- |
| `channel`   | Required: `email`, `sms`, `push`, `ivr` or `whatsapp`.                 |
| `opted_out` | Required: `true` opts the player out, `false` opts the player back in. |

```json
// request
{ "operation": "user_set_channel_opt_out", "params": { "user_id": 1000021, "channel": "sms", "opted_out": true } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Opt the player out of sms messages from Smartico", "executed": true, "result": "You have changed opt-out status for SMS communication. Please note that changes will take effect after few minutes, if you don't see changes immediately please refresh the screen" } }
```

### `user_send_form`

Sends one form to the player, like **Send Form** on the profile. It needs the Forms product. The form must be **Active**; if it is limited to a segment, the player must be in that segment. The account also needs an active campaign that shows personal forms: without one, the form would reach nobody, so the answer is a question instead of a send.

| Parameter | Meaning                              |
| --------- | ------------------------------------ |
| `form_id` | Required. The form's id or its name. |

```json
// request
{ "operation": "user_send_form", "params": { "user_id": 1000021, "form_id": "Welcome survey" } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "form_id": 77, "internal_name": "Welcome survey", "executed": true } }
```

If the player's segments could not be checked, the answer also has `warnings`.

### `user_start_campaign`

Puts the player, or the players of a segment, into a campaign, like **Test with user** / **Test with segment** in the Back-Office. It is a testing tool: the campaign's trigger, segment and entry conditions are skipped for these players. The campaign must be **Active**, and its status does not change. With `segment_id`, the campaign starts for up to 50 players of the segment.

| Parameter     | Meaning                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `audience_id` | Required. The campaign.                                                                                   |
| `segment_id`  | Instead of the player: a segment. Send the player (`user_ext_id` or `user_id`) or `segment_id`, not both. |

```json
// request
{ "operation": "user_start_campaign", "params": { "audience_id": 30512, "user_id": 1000021 } }
// response
{ "type": "ok", "data": { "audience_id": 30512, "user_id": 1000021, "user_ext_id": "p1", "message": "Started for p1 user" } }
```

### `user_stop_campaign`

Stops one player's journey in a campaign. Other players are not affected. To stop a campaign for every player, use `stop_campaign_for_all` (it needs `confirm: true`; see [MCP - Tools and entity types](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-tools-and-entity-types.md)).

| Parameter        | Meaning                                                                                                                                                                                                                                                   |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audience_id`    | Required. The campaign.                                                                                                                                                                                                                                   |
| `engagement_uid` | Required. The player's engagement in that campaign: the **Campaigns** tab of the player shows it, or the golden query `campaign-players` with `only_in_campaign: true`, which lists one row per running journey with the player and its `engagement_uid`. |

```json
// request
{ "operation": "user_stop_campaign", "params": { "audience_id": 30512, "user_id": 1000021, "engagement_uid": "<engagement_uid>" } }
// response
{ "type": "ok", "data": { "audience_id": 30512, "user_id": 1000021, "user_ext_id": "p1", "message": "Campaign stop requested." } }
```

{% hint style="info" %}
The old names `start_campaign`, `stop_campaign_for_player` and `send_form` still work. They run `user_start_campaign`, `user_stop_campaign` and `user_send_form`.
{% endhint %}

## Account flags and markers

### `user_set_state`

Sets several state properties of the player in one call: test account, the Smartico opt-out of each channel, the gamification control group, and markers. Each property goes through the same Back-Office action as its switch on the player's profile, with the same permission and the same line in the player's history.

All properties are checked first, and nothing is sent while one of them is refused. Markers are refused when restricted properties hide them from your Back-Office user, so markers you cannot see are never overwritten. Then they run in the order you give them, and the first failure stops the rest: the answer names what was set and what was not. The wallet currency and GDPR requests are not part of this operation.

| Parameter    | Meaning                                                                           |
| ------------ | --------------------------------------------------------------------------------- |
| `properties` | Required. An object of property names and their new values, from the table below. |

| Property                            | Value                               | What it changes                                                                                                                  |
| ----------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `core_is_test_account`              | `true` or `false`                   | `true` marks the player as a test account, `false` as a real one.                                                                |
| `core_is_email_disabled`            | `true` or `false`                   | The Smartico opt-out of email: `true` opts the player out, `false` back in.                                                      |
| `core_is_sms_disabled`              | `true` or `false`                   | The same, for SMS.                                                                                                               |
| `core_is_push_disabled`             | `true` or `false`                   | The same, for push notifications.                                                                                                |
| `core_is_ivr_disabled`              | `true` or `false`                   | The same, for IVR calls.                                                                                                         |
| `core_is_whatsapp_disabled`         | `true` or `false`                   | The same, for WhatsApp.                                                                                                          |
| `ach_gamification_in_control_group` | `true` or `false`                   | `true` puts the player in the gamification control group (gamification off).                                                     |
| `core_tags`                         | `{ "add": [...], "remove": [...] }` | The player's markers. Only the markers you name change; the others stay. Case does not matter: markers are stored in upper case. |
| `core_public_tags`                  | `{ "add": [...], "remove": [...] }` | The player's JS markers, in the same way.                                                                                        |

```json
// request
{
  "operation": "user_set_state",
  "params": {
    "user_id": 1000021,
    "properties": {
      "core_is_sms_disabled": true,
      "core_tags": { "add": ["vip"], "remove": ["new"] },
      "ach_gamification_in_control_group": false
    }
  }
}
// response
{
  "type": "ok",
  "data": {
    "user_id": 1000021,
    "user_ext_id": "p1",
    "changes": [
      { "property": "core_is_sms_disabled", "action": "Opt the player out of sms messages from Smartico" },
      { "property": "core_tags", "action": "Set the player's markers to [vip] (were [new])" },
      { "property": "ach_gamification_in_control_group", "action": "Take the player out of the gamification control group (gamification on)" }
    ],
    "executed": true
  }
}
// with "dry_run": true the answer has "dry_run": true, the same "changes" (what would be done) and "executed": false
```

### `user_set_test_account`

Marks the player as a test account or as a real account.

{% hint style="warning" %}
`user_set_test_account` still works in this release, but it will be removed in a later one. Use [`user_set_state`](#user_set_state) with `core_is_test_account`.
{% endhint %}

| Parameter | Meaning                                                      |
| --------- | ------------------------------------------------------------ |
| `is_test` | Required: `true` for a test account, `false` for a real one. |

```json
// request
{ "operation": "user_set_test_account", "params": { "user_id": 1000021, "is_test": true } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Mark the player as a test account", "executed": true, "result": "Account test status is scheduled to update to \"test\". Please note that changes will take effect after few minutes, if you don't see changes immediately please refresh the screen" } }
```

### `user_set_markers`

Adds and removes the player's markers (the tags on the profile). Only the markers you name change; the others stay. The call is refused when restricted properties hide the player's markers from your Back-Office user, so markers you cannot see are never overwritten.

{% hint style="warning" %}
`user_set_markers` still works in this release, but it will be removed in a later one. Use [`user_set_state`](#user_set_state) with `core_tags`.
{% endhint %}

| Parameter | Meaning                                                         |
| --------- | --------------------------------------------------------------- |
| `add`     | A list of markers to add. Each marker is a text without commas. |
| `remove`  | A list of markers to remove. Send `add`, `remove` or both.      |

```json
// request
{ "operation": "user_set_markers", "params": { "user_id": 1000021, "add": ["vip"], "remove": ["new"] } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Set the player's markers to [support, vip] (were [new, support])", "executed": true } }
```

### `user_set_gamification_control_group`

Puts the player in the gamification control group, which turns gamification off for the player, or takes the player out of it.

{% hint style="warning" %}
`user_set_gamification_control_group` still works in this release, but it will be removed in a later one. Use [`user_set_state`](#user_set_state) with `ach_gamification_in_control_group`.
{% endhint %}

| Parameter          | Meaning                                                                           |
| ------------------ | --------------------------------------------------------------------------------- |
| `in_control_group` | Required: `true` turns gamification off for the player, `false` turns it back on. |

```json
// request
{ "operation": "user_set_gamification_control_group", "params": { "user_id": 1000021, "in_control_group": true } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Put the player in the gamification control group (gamification off)", "executed": true } }
```

## Tournaments

Both operations need the player's registration in that tournament run.

### `user_set_tournament_score`

Sets the player's score in one tournament run. The score is the new total, not an amount to add. It can be changed only for a registered or finished player, in a run that is open, running, finalizing or finished.

| Parameter                | Meaning                                        |
| ------------------------ | ---------------------------------------------- |
| `tournament_instance_id` | Required. The tournament run.                  |
| `score`                  | Required. The new total score, a whole number. |
| `comment`                | Optional. Stored in the player's history.      |

```json
// request
{ "operation": "user_set_tournament_score", "params": { "user_id": 1000021, "tournament_instance_id": 88123, "score": 1500 } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Set the player's score in tournament run #88123 from 1200 to 1500", "executed": true, "result": "User score is adjusted" } }
```

### `user_change_tournament_registration`

Approves a registration that waits for approval, or cancels a registration. Only a registered player of an open or running run can be cancelled.

| Parameter                | Meaning                                   |
| ------------------------ | ----------------------------------------- |
| `tournament_instance_id` | Required. The tournament run.             |
| `action`                 | Required: `approve` or `cancel`.          |
| `comment`                | Optional. Stored in the player's history. |

```json
// request
{ "operation": "user_change_tournament_registration", "params": { "user_id": 1000021, "tournament_instance_id": 88123, "action": "cancel" } }
// response
{ "type": "ok", "data": { "user_id": 1000021, "user_ext_id": "p1", "action": "Cancel the player's registration in tournament run #88123", "executed": true, "result": "Registration status is changed to 'Cancelled'" } }
```

## Jackpots

### `user_opt_out_jackpot`

Does what **Opt-out** on the **Opted-in users** tab of a jackpot does: no bet of the player contributes to the jackpot any more, and the automatic opt-in never joins them again. Nothing opts the player in again, so the call needs `confirm: true`.

| Parameter        | Meaning                |
| ---------------- | ---------------------- |
| `jp_template_id` | Required. The jackpot. |
| `confirm`        | Required: `true`.      |

```json
// request
{ "operation": "user_opt_out_jackpot", "params": { "user_id": 1000021, "jp_template_id": 45, "confirm": true } }
```

## Example prompts

* *"Show me the profile of player 12345 and their current missions."*
* *"Give player 12345 three spins of the Daily Wheel mini-game and show the game — check it with a dry run first."*
* *"Complete mission 73854 for player p1 with the comment 'asked by support'."*
* *"Take away 50 points from player 12345 without affecting the leaderboard."*
* *"Opt player 12345 out of SMS messages."*
* *"Mark player 12345 as a test account, opt them out of email and add the marker 'vip'."*
* *"Send the 'Welcome survey' form to player 12345."*

More prompts for support, CRM, retention and data teams: [MCP - Prompt library](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-prompt-library).

## FAQ

**Can I check a change before it happens?** Yes, if you want to. Add `dry_run: true` to any `user_` operation run with `exec_operation`. The same checks run, you get the player and the action in words, and nothing is done. Without `dry_run`, the operation runs.

**Why did I get a question instead of a change?** The operation makes the same checks as the Back-Office before it sends anything. Typical reasons: the mission is not unlocked or already completed, the mini-game is not active, the bonus template is disabled or needs an amount, or `confirm: true` is missing for a bonus. The `text` of the answer says which.

**What is the difference between giving a mission and completing it?** `user_give_mission` unlocks a mission that is given manually. `user_complete_mission` completes a mission that is already unlocked and pays its rewards. If the prize waits for a claim, `user_claim_mission_reward` claims it afterwards.

**Does `user_start_campaign` check whether the player qualifies?** No. It is a testing tool: the trigger, segment and entry conditions of the campaign are skipped. The campaign must be Active.

**How can I see who made a change?** The change is in the player's history like a change made in the Back-Office, with "MCP" and your comment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-operations-on-the-users.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
