> 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-label-and-brand-settings.md).

# MCP - label and brand settings

The Smartico Model Context Protocol (MCP) Server provides dedicated read operations and entity discovery tools for inspecting account configuration, brand parameters, gamification widget options, communication gateways, and delivery caps. These tools supply the foundational vocabulary—such as available account currencies, enabled languages, active brands, and delivery rate limits—that external AI assistants and automated scripts need before building segments, drafting campaigns, configuring messaging templates, or troubleshooting delivery volumes. One operation, `set_label_setting`, also changes a label or brand setting, with the same rights as the **Label settings** screen in the Back-Office.

## Overview of Configuration Tools

The table below outlines the MCP tools used to read account configuration, brand details, widget settings, gateways, and communication caps, and the one operation that changes a setting.

| Tool / Entity                               | MCP Invocation                        | What It Reads                                                                                    | Parameters                                                                                                             | Supported Actions |
| ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------- |
| **Account Info** (`get_label_info`)         | `read_operation`                      | Currencies, languages, brands, products, reporting timezone, and communication caps              | None (`params: {}`)                                                                                                    | Read-only         |
| **Settings Search** (`get_label_settings`)  | `read_operation`                      | Account-level and brand-level configuration settings matching search keywords                    | `keywords` (required), `brand_id` (optional)                                                                           | Read-only         |
| **Change a Setting** (`set_label_setting`)  | `exec_operation`                      | Changes one account-level or brand-level setting, named by its key                               | `key` (required), `value` (required unless `revert_to_default`), `brand_id` (optional), `revert_to_default` (optional) | Update            |
| **Widget Settings** (`get_widget_settings`) | `read_operation`                      | Visual themes, layout, section order, header counters, and feature options for the player widget | `users` (required: `"real"` or `"test"`), `brand_id` (optional)                                                        | Read-only         |
| **Mail Gateway** (`mail_gateway`)           | `entity_list`, `entity_get`           | Configured email sending connections, sender addresses, reply-to addresses, and brand routing    | Filters (`name`, `crm_brand_id`, `use_as_default`, provider)                                                           | Read-only         |
| **Instant Message Gateway** (`im_gateway`)  | `entity_list`, `entity_get`           | Configured SMS, WhatsApp, Viber, Telegram, RCS, and Custom IM sending connections and sender IDs | Filters (`name`, `crm_brand_id`, `im_provider_type_id`, provider)                                                      | Read-only         |
| **IVR Gateway** (`ivr_gateway`)             | `entity_list`, `entity_get`           | Configured voice-call connections and caller IDs                                                 | Filters (`name`, `crm_brand_id`, `use_as_default`, provider)                                                           | Read-only         |
| **Communication Caps**                      | `read_operation` via `get_label_info` | Global delivery limits (per channel/category) and personal player fatigue limits                 | None (returned in `get_label_info`)                                                                                    | Read-only         |

{% hint style="info" %}
**Settings can be changed one at a time; gateways and caps are read-only through MCP.** The `set_label_setting` operation changes one label or brand setting, with the same rights as the **Label settings** screen (see [Changing a Setting](#changing-a-setting-set_label_setting) below). Delivery gateways and communication caps cannot be created, updated, or deleted via MCP. They are configured and managed exclusively in the Smartico Back-Office by authorized administrators. Sensitive credentials (such as vendor API keys, salts, webhook tokens, and gateway passwords) are never returned through MCP, and settings that hold them cannot be changed through MCP.
{% endhint %}

***

## Account Overview (`get_label_info`)

The `get_label_info` operation returns the core operational parameters of your account. Call this operation once at the beginning of an AI session or automated script to establish the valid vocabulary of your environment.

### Why Call `get_label_info` First?

Every Smartico account operates with its own specific internal IDs and configured options that cannot be guessed:

* **Currencies:** Monetary amounts across bonus templates, rules, and store items require the account's internal currency ID alongside the currency code.
* **Languages:** Template variations and localization keys require the specific language codes enabled on the account.
* **Brands:** Multi-brand setups require specific brand IDs when scoping campaigns, segments, or banner placements to a brand.
* **Communication Caps:** Global and personal rate limits explain why a campaign communication step may deliver to fewer users than the estimated audience.

### Request Format

The operation takes no operation-specific parameters (`params: {}`). To query another label authorized on your MCP access token, pass `label_id` as a top-level argument.

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "read_operation",
      "arguments": {
        "operation": "get_label_info",
        "params": {}
      }
    }
  }'
```

### Response Fields

* `label_id` (number): The account identifier.
* `label_name` (string): The account display name.
* `default_currency` (string): The fallback currency code (e.g., `"EUR"`).
* `currencies` (array): All currencies active on the account, each with `id` (number) and `name` (string).
* `languages` (array): Active language codes (e.g., `["en", "de", "es"]`).
* `brands` (array): Configured brands on the account. Each entry includes:
  * `id` (number): The internal brand ID used in per-brand configurations.
  * `name` (string): The brand display name.
  * `ext_brand_id` (string | null): The external identifier of the brand on the operator platform.
* `products` (array): Enabled product verticals, each with `id` and `name` (e.g., Casino, Sport).
* `timezone` (string): The time zone the Back-Office shows times in, as a fixed offset such as `"UTC +2"` (`"UTC"` when none is set).
* `utc_offset_minutes` (number): The same offset in minutes (for example, `120` for `"UTC +2"`).
* `global_caps` (array): Global account-wide communication rate limits (see [Communication Caps](#communication-caps--delivery-limits)).
* `personal_caps` (array): Per-player communication fatigue limits.

***

## Searching Settings (`get_label_settings`)

The `get_label_settings` operation searches, by keyword, the settings of the **Label settings** screen in the Back-Office (or of a brand's settings): bonus mechanics, gamification rules, compliance checks, integration behaviors and more. It covers the settings of that screen for your account and your role: the ones it shows, and the ones it hides until a switch on the same screen is turned on (or, for a few, off). For example, while **Level logic: points + behavior counters** is off, the level logic settings are still listed, with `hidden_until` naming that switch; they cannot be changed until the switch is on. A setting your account cannot have (another account type, or a product your account does not have and no switch on the screen turns on) cannot be read or changed through the MCP.

### Search Rules

* **Keyword requirement:** The full list of settings cannot be retrieved at once. The `keywords` parameter is required and accepts an array of 1 to 10 search strings.
* **Matching logic:** A setting matches if any supplied keyword appears in its key, title, or description. Searches are case-insensitive, and underscores are treated as spaces (for example, searching `"account status"` matches settings related to user account status checks).
* **Two-letter keywords:** Short keywords of two letters (such as `"ai"`) match only as whole words.
* **Brand-level scoping:** By default, `get_label_settings` evaluates settings at the account (label) level. Pass the optional `brand_id` parameter to inspect settings and overrides for a specific brand.

### Request Format

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "read_operation",
      "arguments": {
        "operation": "get_label_settings",
        "params": {
          "keywords": ["bonus", "cap"]
        }
      }
    }
  }'
```

To search for settings on a specific brand:

```json
{
  "operation": "get_label_settings",
  "params": {
    "keywords": ["deposit"],
    "brand_id": 12
  }
}
```

### Result Structure & Inheritance

The operation returns the number of matches found, the number of records returned (at most 40 per search, key and title matches first), and an array of matching setting objects:

* `key` (string): The programmatic key of the setting.
* `title` (string): The human-readable name displayed on the Back-Office settings screen.
* `description` (string): A summary of the setting's purpose and functionality.
* `value`: The setting's effective value currently in force.
* `value_source` (string): Indicates the origin of the effective value:
  * `"label"`: Explicitly set at the account level.
  * `"brand"`: Overridden specifically for the requested brand.
  * `"default"`: Inherited from system defaults because no override was set.
* `default_value`: The baseline value applied when no explicit override exists.
* `type` (string): The data type (e.g., text, switch, number, json, select, reference).
* `can_edit` (boolean): Indicates whether the Back-Office user associated with the token has permission to edit this setting in the UI. The same permission applies to `set_label_setting`.
* `value_hidden` (boolean): Set to `true` for credential fields (API keys, salts, webhook tokens, passwords). When `true`, both `value` and `default_value` are set to `null` to prevent secret leakage.
* `hidden_until` (string | null): `null` when the screen shows the setting. Otherwise the switches the screen waits for before it shows the setting, for example `"GAMIFICATION_LEVELS_LOGIC2 on"`. Until then the setting can be read but not changed: `set_label_setting` refuses it.
* `brands_overriding` (string | null): When querying at the account level, the brands that set their own value, as `"Name (#id)"` separated by commas.

***

## Changing a Setting (`set_label_setting`)

Changes one label setting, or the value of one brand. Name the setting by its key, exactly as `get_label_settings` returns it. Run it with `exec_operation`. It is the same save as the **Label settings** screen in the Back-Office, made as the Back-Office user of the token: the same edit permissions, the same value rules, and the same line in the change history. The platform uses a saved value within 1 minute.

Which settings you can change depends on your Back-Office role. In `get_label_settings`, `can_edit: true` marks the settings your user can change.

| Parameter           | Meaning                                                                                                                                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`               | Required. The setting's key, exactly as `get_label_settings` returns it.                                                                                                                                                |
| `value`             | Required unless `revert_to_default` is `true`. The new value, in the setting's type: `true` or `false`, a number, a text, a list of ids, or a JSON object. For a JSON setting, send the object itself, not a JSON text. |
| `brand_id`          | Optional. Changes this brand's value instead of the account (label) value.                                                                                                                                              |
| `revert_to_default` | Optional. `true` removes the value at this level, so the default one level up applies again.                                                                                                                            |

`dry_run: true` is optional and goes next to `params`, not inside it. It runs every check of the save and saves nothing. Without it, the call saves.

The operation refuses, with an explanation:

* a setting that the **Label settings** screen of your account does not have;
* a setting that the screen hides until a switch is turned (`hidden_until` is set): the answer names each switch and how to turn it (with `set_label_setting`, in the Back-Office, or by a user whose role may change it);
* a setting that your Back-Office user may not change;
* a setting that holds a credential (`value_hidden: true` in `get_label_settings`);
* an account-level property that is not a label setting;
* a setting that the system sets itself (such as the times of the last and next level recalculation): nobody can change it, through MCP or in the Back-Office;
* a value of the wrong type (true/false, number, text, list of ids, JSON object), or one the setting does not allow (the screen's choices, ranges and required fields).

Sending the value that is already in effect answers "Nothing to change" and saves nothing.

**Level logic definition.** `GAMIFICATION_LEVELS_LOGIC2_DEFINITION` is changed by Smartico staff. Each new or changed counter SQL in it is checked with a free BigQuery dry run on the label's own data warehouse. The SQL must be one `SELECT` that returns `user_id` (a whole number) and `value` (a number), read only the label's own tables (`dwh_ext_<label_id>.<table>`), and read at most 100 GB.

```json
// request: the arguments of exec_operation
{
  "operation": "set_label_setting",
  "params": { "key": "DWH_MONTHLY_USAGE_SOFT_ALERT_TB", "value": 20 }
}
// response
{
  "executed": true,
  "key": "DWH_MONTHLY_USAGE_SOFT_ALERT_TB",
  "title": "DWH usage alert: monthly limit, TB",
  "previous_value": "10",
  "value": "20",
  "value_source": "label",
  "note": "Saved; the platform uses the new value within 1 minute."
}
// response of the same request with "dry_run": true
{
  "dry_run": true,
  "executed": false,
  "key": "DWH_MONTHLY_USAGE_SOFT_ALERT_TB",
  "title": "DWH usage alert: monthly limit, TB",
  "current_value": "10",
  "current_value_source": "label",
  "new_value": 20,
  "revert_to_default": false,
  "note": "Every check of the save passed (permission, value rules, and for the Logic 2 definition the counter SQL dry run). Nothing was saved."
}
// a number setting is read back as text ("20"); both 20 and "20" are accepted as a value
```

***

## Gamification Widget Settings (`get_widget_settings`)

The `get_widget_settings` operation retrieves the visual, structural, and behavioral configuration of the player-facing gamification widget (the overlay displaying missions, store, leaderboards, mini-games, and inbox).

In the Back-Office, these settings are managed under **Label → Label settings → Widget / Real users** and **Widget / Test users**, as well as the corresponding tabs under **Label → Brands → \[Selected Brand]**.

### Parameters

* `users` (string, required): Accepts either `"real"` (settings presented to genuine players) or `"test"` (settings presented to test accounts).
* `brand_id` (number, optional): Inspects widget configuration for a specific brand.

### Inheritance and Fallback Rules

1. **Test User Fallback:** If an account has not saved dedicated test settings, querying with `users: "test"` returns the real users' configuration. The returned `settings_key` will reference the real-users key, accompanied by an explanatory note.
2. **Brand Customization Switch:** In multi-brand environments, each brand possesses a setting: *"Enable custom gamification settings for this brand"*.
   * If this toggle is **disabled**, the brand inherits the account-level widget settings. The API returns `settings: null`, `brand_custom_settings: false`, and an informational note directing the caller to query without `brand_id`.
   * If this toggle is **enabled**, the brand uses its own custom settings, returning `value_source: "brand"`.
3. **System Defaults:** If no custom widget settings have ever been saved on the account or brand, `settings: null` is returned, and the front-end widget operates on its internal platform defaults.

### Request Format

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "read_operation",
      "arguments": {
        "operation": "get_widget_settings",
        "params": {
          "users": "real"
      }
      }
    }
  }'
```

### Key Configuration Areas in the Result

When `settings` is populated, it contains configuration objects structured across several functional sections:

* **General & Theme:**
  * `theme`: The primary visual theme name.
  * `widget_visual_addon`: Seasonal or promotional overlays (e.g., Christmas, Halloween, Easter, Football).
  * `allowed_languages`: Permitted language options for the widget.
  * `enable_qr_scanner`, `username_change_allowed`, `avatars`: Feature toggles.
  * `widget_disclaimer_text`: Terms and conditions or promotional disclaimer text displayed at the bottom of the widget.
* **Sections Visibility & Order:**
  * `sections`: Array of `{ type, visibility }` defining which navigation tabs appear and in what display order. Section types include `home`, `missions`, `leaderboard`, `tournaments`, `clans`, `levels`, `badges`, `saw` (mini-games), `matchx`, `quiz`, `store`, `bonus`, `activity` (Inbox), `jackpots`, and `activity-log`; a number is the id of a custom section. Visibility values are `"all"`, `"test"` (visible to test accounts only), or `"none"` (hidden).
  * `sections_home`: Sections pinned to the mobile home screen header.
* **Header Indicators:**
  * Counter positions (1 to 6, or `"off"`) and click behaviors for points, gems, diamonds, active missions, level progress, badges, and available mini-game spins on desktop and mobile.
* **Feature Display Rules:**
  * `missions_overview`: Filter rules for the missions landing tab (e.g., hiding completed or locked missions).
  * `store_default_ordering`: Sorting logic for store items based on purchase eligibility, priority, or price.
  * `bonus_widget_history_days`: How many days of bonus history are visible to players.

***

## Communication Gateways

Sending gateways connect Smartico to third-party communication service providers for delivering email, instant messages, and voice calls. In MCP, gateways are exposed as three read-only entity types:

* `mail_gateway`: Email sending connections.
* `im_gateway`: Instant message connections across SMS, WhatsApp, Viber, Telegram, RCS, and Custom IM.
* `ivr_gateway`: Interactive Voice Response (IVR) phone call connections.

### Why Inspect Gateways via MCP?

When an AI assistant or script builds a campaign flow containing communication nodes (such as *Send Email* or *Send SMS*), the node requires:

1. A valid gateway identifier passed in the `provider` property.
2. A valid sender address or ID (selected from the gateway's `from_options`).
3. An optional reply-to address (from `reply_to_options`).

Reading gateways ensures that campaign automation drafts reference valid infrastructure and authorized sender IDs.

### Gateway Operations Supported

Gateways support **only** `entity_list` and `entity_get`:

* `entity_list`: Lists available gateways with optional filtering.
* `entity_get`: Fetches complete gateway metadata by ID.
* `entity_create` and `entity_update`: **Not supported.** Creating or modifying gateways through MCP is blocked.

{% hint style="warning" %}
**Credential security:** Service provider credentials (API keys, account secrets, and authentication passwords) are never returned through MCP. Gateways are set up, authenticated, and maintained exclusively in the Back-Office under **Label → Gateways** (**Mail**, **Instant messages**, **IVR**).
{% endhint %}

### Listing Mail Gateways (`mail_gateway`)

Filter email gateways by name, brand, default status, or email provider ID.

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "entity_list",
      "arguments": {
        "entity_type": "mail_gateway",
        "filters": {
          "use_as_default": true
        },
        "limit": 5
    }
    }
  }'
```

#### Mail Gateway Fields

* `id` (number): The gateway identifier passed to campaign communication nodes as `provider`.
* `name` (string): The internal gateway name.
* `crm_brand_id` / `crm_brand_name`: The brand served by this gateway (or `"Any"` if shared across all brands).
* `use_as_default` (boolean): Whether this gateway is used automatically when a campaign step does not specify a provider.
* `from_options` (array of strings): Authorized `"Sender Name <email@example.com>"` sender addresses.
* `reply_to_options` (array of strings): Authorized reply-to addresses.
* `selection_conditions_readable` (string | null): Player property conditions (such as country or currency) used when automatic gateway routing is active.

### Listing Instant Message Gateways (`im_gateway`)

The `im_gateway` entity covers multiple messaging channels. Filter by `im_provider_type_id` to inspect gateways for a specific channel:

* `1`: SMS
* `2`: WhatsApp
* `3`: Viber
* `4`: Custom IM
* `5`: Telegram
* `6`: RCS

```bash
curl -X POST https://aichat-api<N>.smartico.ai/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "entity_list",
      "arguments": {
        "entity_type": "im_gateway",
        "filters": {
          "im_provider_type_id": 1
        },
        "limit": 10
      }
    }
  }'
```

#### Instant Message Gateway Fields

* `id` (number): The gateway ID.
* `im_provider_type_id` / `im_provider_type_name`: The communication channel (e.g., SMS, WhatsApp).
* `from_options` (array of strings): Authorized alphanumeric or numeric sender IDs.
* `from_field_not_required` (boolean): Indicates whether the provider allows sends without an explicit sender ID.
* `sms_provider_id` / `sms_provider_name`: The underlying messaging vendor.

### Automatic Gateway Selection (`-1`)

In multi-brand or multi-region setups, campaign communication steps can specify `provider: -1` (*Automatic Selection*). The platform evaluates incoming player properties (such as brand, country, or registration currency) against gateway selection rules (`selection_conditions_readable`) to select the correct delivery connection dynamically.

***

## Communication Caps & Delivery Limits

Communication caps protect sending domain reputation, prevent communication spam, control third-party messaging costs, and reduce player fatigue. Caps are configured in the Back-Office under **Label → Communication caps** (**Per-user** and **Global**) and are inspected via MCP in the `global_caps` and `personal_caps` arrays returned by `get_label_info`.

### Global Caps vs. Personal Caps

| Feature          | Global Caps (`global_caps`)                                                                                                  | Personal Caps (`personal_caps`)                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Scope**        | Account-wide across all players                                                                                              | Per individual player                                             |
| **Primary Goal** | Protect provider rate limits, IP/domain warmup, and credit spend                                                             | Prevent player fatigue and message spam                           |
| **Time Windows** | Set by the cap's **Time calculation mode**: sliding window, calendar time, or the player's time zone (the hour always rolls) | Same modes as global caps                                         |
| **Message Gap**  | Not applicable                                                                                                               | Minimum gap between sends (`limit_time_between_sec`, default 30s) |
| **Exemptions**   | Test accounts bypass caps                                                                                                    | Test accounts bypass caps                                         |

### Cap Data Structure

Each entry in `global_caps` and `personal_caps` defines limits for a channel and campaign category pair:

* `activity_type_id` / `activity_name`: The communication channel (Email, SMS, Push, Popup, Inbox, IVR, WhatsApp, Viber, Telegram).
* `audience_category_id` / `category_name`: The campaign category (e.g., Marketing, Operational, or `-1` representing *Any*).
* `limit_per_hour`: Maximum allowed sends per hour (`null` if unconstrained).
* `limit_per_day`: Maximum allowed sends per day (`null` if unconstrained).
* `limit_per_week`: Maximum allowed sends per 7-day period.
* `limit_per_month`: Maximum allowed sends per 30-day period.
* `limit_time_between_sec` (*Personal caps only*): Minimum required delay in seconds between two messages sent to the same user on that channel.
* `cap_period_type_id` / `cap_period_type_name`: How the day, week, and month are counted: `1` Sliding window (the last 24 hours, 7 days, 30 days), `2` Calendar time (the current day, week from Monday, and month in the time zone `cap_period_time_zone`), `3` User time zone (the same calendar periods in each player's own time zone).

A row with `activity_type_id: -2` (*Offline (Combined)*) is one cap on all offline channels together (Email, IVR, Push, SMS, WhatsApp, Viber, Telegram, RCS, Custom IM). It applies on top of each channel's own cap.

### Campaign Step Interaction (`caps_impact`)

When drafting or reviewing campaign flows via MCP, each communication step defines how it interacts with communication caps through its `caps_impact` setting:

* `1`: **Respects both caps** (default) — Delivery is aborted if either global or personal caps are exceeded.
* `2`: **Ignores both caps** — Used for mission-critical transactional messages (such as password resets or withdrawal confirmations).
* `3`: **Ignores global caps only** — Respects user fatigue limits while bypassing account-wide sending thresholds.
* `4`: **Ignores personal caps only** — Respects account-wide quotas while overriding player fatigue limits.

{% hint style="info" %}
**Delivery Failure Behavior:** When an outgoing message is blocked because a cap threshold is reached, delivery fails immediately. In communication logs and analytics, these failed sends are categorized under cap limits (cannibalisation). Test accounts never encounter cap restrictions.
{% endhint %}

***

## Frequently Asked Questions

### Why are API keys, salts, and passwords masked or null when queried through MCP?

Smartico enforces strict credential isolation for all MCP connections. When using `get_label_settings`, settings containing credentials (such as API secret keys, service salts, cloud storage keys, or webhook authorization headers) return `value_hidden: true` and have their values stripped (`null`). Similarly, `mail_gateway`, `im_gateway`, and `ivr_gateway` never expose vendor API credentials. This prevents sensitive credentials from being passed to AI language models. `set_label_setting` refuses to change these settings. Administrators can manage these credentials directly in the Back-Office UI.

### Can I update label settings, brand settings, or gateways using MCP tools?

Label and brand settings: yes, one setting per call, with `set_label_setting` (see [Changing a Setting](#changing-a-setting-set_label_setting)). It applies the same permissions and value rules as the **Label settings** screen, and it cannot change settings that hold credentials. In `get_label_settings`, `can_edit: true` marks the settings your user can change. Communication gateways and delivery caps are read-only through MCP: `entity_create` and `entity_update` reject modifications to them. These changes must be carried out in the Smartico Back-Office by users with appropriate administrative permissions.

### How do I find the correct currency or brand ID when creating templates or bonuses?

Call `read_operation` with `get_label_info`. The response provides the authoritative list of currencies with their numerical IDs (such as `{ "id": 1, "name": "EUR" }`), language codes, and brand IDs. Use these exact identifiers when populating monetary fields or brand overrides in other MCP tools.

### Why did my campaign communication node deliver to fewer users than the estimated audience?

If an audience segment contained 5,000 players but a communication node delivered fewer messages, review the communication caps in `get_label_info`. Players who have already reached a personal cap for the period, or got a message within the minimum gap (`limit_time_between_sec`), are skipped. Additionally, if the account reached its daily global limit on that channel and category, later sends fail at once. The cap's `cap_period_type_name` says how the day is counted. Check if the communication step was configured with `caps_impact: 1`.

### What happens if a brand does not have custom widget settings configured?

When querying `get_widget_settings` for a brand where the *"Enable custom gamification settings for this brand"* toggle is off, the tool returns `settings: null` and `brand_custom_settings: false`, along with a note explaining that the brand inherits the account-level settings. To inspect the active configuration for that brand's players, run `get_widget_settings` without the `brand_id` parameter.

### How can I search for bonus caps or specific feature toggles?

Call `get_label_settings` with relevant search terms in the `keywords` array (for example, `keywords: ["bonus", "cap"]` or `keywords: ["raffle", "limit"]`). The tool searches keys, titles, and descriptions, returning the effective value, whether it originates from the label or a brand, and whether your user can change it (`can_edit`).

***

## Related Documentation

* [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server.md) — Architecture overview, connection options, and supported tool catalog.
* [MCP Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md) — Permission governance, system access tiers, and profile assignments.
* [MCP - How to manage images](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-how-to-manage-images.md) — Media asset management, image uploads, and CDN integration via MCP.


---

# 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-label-and-brand-settings.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.
