> 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-tools-and-entity-types.md).

# MCP - Tools and entity types

This page is the reference for what the [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server.md) exposes: the 18 tools, the operations behind `read_operation` and `exec_operation`, and the entity types you can read, create, or update. To connect an AI assistant or call the API, see [MCP - Connection and security](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connection-and-security.md). Step-by-step instructions for each client: [MCP - Connect Claude, ChatGPT, Cursor and other MCP Clients](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-connect-claude-chatgpt-cursor-and-other-mcp-clients).

## The tools

The server exposes 18 tools. Most work flows start with discovery (`entity_types_list` → `entity_describe`) and then read or write.

| Tool                         | What it does                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_types_list`          | Lists every object type the server exposes, with a one-line description. A type your label cannot use (its product is not enabled) is marked `not_enabled`, with the reason. Start here.                                                                                                                                                      |
| `entity_describe`            | Returns the full field reference and workflow for one object type. Call it before creating or updating.                                                                                                                                                                                                                                       |
| `entity_list`                | Lists records of an object type, with optional filters, sorting, limit, and offset. Returns 20 records by default. Types with long or wide records list their main columns (the answer names the columns left out); `only_fields` picks the columns, `whole_record: true` gives whole records.                                                |
| `entity_get`                 | Fetches a single record by id. Some records are long (a mail body, a popup design): `only_fields` returns only the fields you need.                                                                                                                                                                                                           |
| `entity_get_many`            | Fetches up to 20 records of one object type in one call; each is what `entity_get` returns. An id that is not found or not allowed is listed under `errors`, and the other records are still returned.                                                                                                                                        |
| `entity_create`              | Creates a record. An optional `dry_run: true` only checks the request: it answers "ok" or what is wrong, and saves nothing.                                                                                                                                                                                                                   |
| `entity_update`              | Updates a record: send only the fields that change (an omitted field keeps its value). `edits` find and replace text inside a long field, such as a mail body. The answer shows the fields it changed, before and after. An optional `dry_run: true` only checks the request.                                                                 |
| `read_operation`             | Runs read-only platform operations (e.g. read a campaign flow). Safe to auto-approve.                                                                                                                                                                                                                                                         |
| `exec_operation`             | Runs operations that change state or consume AI tokens (e.g. start a campaign, estimate an audience). Supports `dry_run`.                                                                                                                                                                                                                     |
| `read_resource`              | Reads a reference document — creation/update guides, format specs, or the list of labels your token can use.                                                                                                                                                                                                                                  |
| `get_product_knowledge`      | Searches the product knowledge base and returns relevant passages with source links. Read-only.                                                                                                                                                                                                                                               |
| `get_analytics_bi_structure` | Discovers analytics data-warehouse tables in two steps (search by topic, then load full definitions for up to 5 tables at a time). Called with no arguments, it returns a short map of every table. Read-only.                                                                                                                                |
| `exec_sql`                   | Executes a single read-only SQL query against the analytics data warehouse, returning rows as CSV with the column types and the tokens used; `as_file: true` gives the whole result as a CSV file behind a download link. Consumes AI tokens based on data scanned. Supports `dry_run`, which tells the token cost without running the query. |
| `find_golden_queries`        | Searches the golden queries: fixed data questions written and tested by Smartico (for example, who received, opened or clicked a campaign's messages). Read-only.                                                                                                                                                                             |
| `run_golden_query`           | Runs a golden query by its key with your values and returns rows as CSV, like `exec_sql`. Consumes AI tokens. Supports `dry_run`.                                                                                                                                                                                                             |
| `get_golden_query_sql`       | Returns the SQL of a golden query, to change and run with `exec_sql`. Runs nothing.                                                                                                                                                                                                                                                           |
| `report_problem`             | Reports a tool error, unexpected result, validation rejection, or missing capability directly to the Smartico team. An AI reads each report at once and answers the assistant. Always available across all access profiles.                                                                                                                   |
| `batch`                      | Sends up to 20 tool calls in one request. They run in order, and each is checked and answered as if it were sent alone (access profile, `label_id`, `dry_run`). One failing call does not stop the others, and a call cannot use another call's result. Always available across all access profiles.                                          |

Alongside these tools, the server also offers ready-made prompts and reference guides that a supporting MCP client can surface to help you get started.

Tool availability for each connection is governed by the assigned access profile (e.g., Viewer, Editor, Analyst, Full access). See [MCP Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md) for full details on tool grant groupings, and [MCP for Data Analysis](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-for-data-analysis.md) for guides on data warehouse analysis tools.

For the golden queries and their current list, see [MCP - Golden queries](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-golden-queries).

{% hint style="info" %}
**TAP accounts.** On a TAP (The Affiliate Platform) account MCP only reads, and it has tools and entity types of its own: affiliates, deals, sub-affiliate deals, brands, destination links and the affiliate analytics (`get_affiliate_analytics_structure`, `exec_affiliate_sql`). The tools, operations and entity types on this page work on Smartico CRM labels. See [MCP Server](https://help.theaffiliateplatform.com/apis-and-configurations/mcp-server) in the TAP help center.
{% endhint %}

{% hint style="info" %}
**Live reference.** An interactive reference and testing environment for all tools, resources, and prompts is in the backoffice under **MCP → Playground**. Token usage history is tracked under **MCP → Usage**, and credentials are managed under **MCP → Access tokens**.
{% endhint %}

### Operations

`read_operation` and `exec_operation` cover actions that don't map to a simple create/update. The read-only ones can also be run through `exec_operation`, but `read_operation` is the preferred, safe-to-auto-approve way to run them.

There are 96 operations: 30 read operations and 66 actions.

**Read-only (via `read_operation`):**

| Operation                         | Purpose                                                                                                                                                                                                                    |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow_get`                        | Read a campaign's flow as an outline: one row per step, without its settings.                                                                                                                                              |
| `flow_get_nodes`                  | Read up to 20 steps of a flow with their full settings.                                                                                                                                                                    |
| `flow_describe_activity`          | List the configurable fields of a flow step type before adding or editing it.                                                                                                                                              |
| `list_stop_convert_rules`         | Read a campaign's stop/convert rules.                                                                                                                                                                                      |
| `list_campaign_tags`              | Read a campaign's tags (shared `{{campaign.<key>}}` personalization values).                                                                                                                                               |
| `search_bonus_type_field_options` | Search options and dropdown values for dynamic bonus type configuration fields.                                                                                                                                            |
| `search_property_values`          | Search the values of a property (id and name) beyond the first 200 that `entity_get` lists.                                                                                                                                |
| `list_banner_placement_links`     | Read active banner placement links and mappings.                                                                                                                                                                           |
| `get_label_info`                  | Read account configuration including currencies, languages, brands, products, timezone, and communication limits.                                                                                                          |
| `get_label_settings`              | Search account and brand configuration settings by keyword. It also lists the settings that a switch of the screen hides (read-only until the switch is turned); `can_edit: true` marks the settings your user can change. |
| `get_widget_settings`             | Read gamification widget settings (visual theme, section display, header counters) for real or test users at the account or brand level.                                                                                   |
| `user_get_state`                  | Read one player's profile overview: ids, brand, level counters and property values.                                                                                                                                        |
| `user_get_missions`               | Read one player's missions now, with progress and prizes waiting for a claim.                                                                                                                                              |
| `get_leaderboard_standings`       | Read a leaderboard's players with their points and position, for the running period or a finished one.                                                                                                                     |
| `get_clan_members`                | Read the members of one clan, highest score first.                                                                                                                                                                         |
| `get_tournament_runs`             | Read a tournament's runs, newest first.                                                                                                                                                                                    |
| `get_tournament_standings`        | Read the players of one tournament run with score, place and prize, and the clans of a clan tournament's run.                                                                                                              |
| `get_jackpot_pots`                | Read a jackpot's pots (amounts, dates, winner, approval), newest first.                                                                                                                                                    |
| `get_jackpot_pot_players`         | Read the players of one jackpot pot with their contribution and win.                                                                                                                                                       |
| `get_jackpot_opt_ins`             | Read the players opted in to a jackpot, and when they left.                                                                                                                                                                |
| `sport_game_search_feed_events`   | Search the matches of the sports feed for a MatchX or Quiz round.                                                                                                                                                          |
| `list_folders`                    | Read the folders of a screen, or one folder with the records in it.                                                                                                                                                        |
| `get_usage`                       | Read where a record is used, and what keeps it from being archived or disabled.                                                                                                                                            |
| `segment_import_status`           | Read where the import of an Imported (CSV) segment stands.                                                                                                                                                                 |
| `vibe_get_files`                  | Read a Vibe Studio project's files: the list, the structure, or the content of chosen files.                                                                                                                               |
| `vibe_run_status`                 | Read the state of a Vibe Studio AI run, waiting for it to end if asked.                                                                                                                                                    |
| `vibe_preview`                    | Build a Vibe Studio project and return screenshots as a chosen player sees it.                                                                                                                                             |
| `vibe_get_links`                  | Read whether a Vibe Studio project is published, its address and the code to place it.                                                                                                                                     |
| `vibe_references`                 | List the templates a Vibe Studio AI run can use as a reference.                                                                                                                                                            |
| `vibe_commands`                   | List the slash commands a Vibe Studio AI run of a project can start with.                                                                                                                                                  |

For detailed instructions on exploring account configuration and searching brand parameters via read operations, and on changing a setting with `set_label_setting`, see [MCP - label and brand settings](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-label-and-brand-settings.md).

**State-changing or token-costing (via `exec_operation`):**

| Operation                      | Purpose                                                                                                                                                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `estimate_audience`            | Estimate how many users match conditions, a behaviour definition, or an existing segment. Consumes AI tokens.                                                                                                                                                |
| `clone_campaign`               | Duplicate a campaign into a new draft (copies flow and tags).                                                                                                                                                                                                |
| `stop_campaign_for_all`        | Stop a running campaign for all users across the account (requires confirmation).                                                                                                                                                                            |
| `change_campaign_speed`        | Change the execution throttle of a running scheduled campaign.                                                                                                                                                                                               |
| `flow_add_node`                | Add a step (delay, points, bonus, wait-for-event, split, or a communication send) to a flow, or a whole branch of steps in one call. `insert_before` puts the new step in front of an existing one; a merge connection leads a branch into an existing step. |
| `flow_update_node`             | Change a flow step's parameters, move it, or change its status.                                                                                                                                                                                              |
| `flow_set_edge`                | Edit the branch leading into a step, or move the step with its subtree under another step.                                                                                                                                                                   |
| `flow_copy_node`               | Copy or move a step and its subtree under another parent.                                                                                                                                                                                                    |
| `flow_annotation`              | Add, update, delete, or list flow canvas notes.                                                                                                                                                                                                              |
| `flow_layout`                  | Place every step of the flow tidily on the canvas in one call.                                                                                                                                                                                               |
| `set_stop_convert_rule`        | Create or edit a stop/convert rule.                                                                                                                                                                                                                          |
| `remove_stop_convert_rule`     | Delete a stop/convert rule.                                                                                                                                                                                                                                  |
| `set_campaign_tag`             | Create or edit a campaign tag value.                                                                                                                                                                                                                         |
| `remove_campaign_tag`          | Delete a campaign tag value.                                                                                                                                                                                                                                 |
| `set_banner_placement_link`    | Link a banner variation to a banner placement.                                                                                                                                                                                                               |
| `remove_banner_placement_link` | Remove a banner link from a placement.                                                                                                                                                                                                                       |
| `create_folder`                | Create a folder on a screen.                                                                                                                                                                                                                                 |
| `add_to_folder`                | Put records in a folder.                                                                                                                                                                                                                                     |
| `remove_from_folder`           | Take records out of a folder (the records stay).                                                                                                                                                                                                             |
| `set_label_setting`            | Change one label or brand setting, as on the **Label settings** screen, with the same permissions. A setting the screen does not show is refused, naming the switch that shows it.                                                                           |
| `upload_media`                 | Upload an image, video, audio, or document file to the media library from a public HTTPS URL or base64 data.                                                                                                                                                 |
| `segment_import_upload`        | Imported (CSV) segment, step 1: send a list of players (ids, or the file of an `exec_sql` result) to be checked.                                                                                                                                             |
| `segment_import_start`         | Imported (CSV) segment, step 2: once the check is done, create the segment or replace its list (asks for confirmation).                                                                                                                                      |
| `test_avatar_prompt`           | Test an avatar AI prompt on an avatar to generate a preview image before saving. Consumes AI tokens.                                                                                                                                                         |
| `test_formula`                 | Compute a dynamic reward formula for up to 10 players over a period, paying nothing. Consumes AI tokens.                                                                                                                                                     |
| `reset_leaderboard_points`     | Set every player's points of an active leaderboard's period to 0 (asks for confirmation).                                                                                                                                                                    |
| `finalize_leaderboard`         | Finalize an active leaderboard now, as if its period had ended: the top places get their prizes and points start again from 0 (asks for confirmation).                                                                                                       |
| `add_clan_members`             | Put players in a clan.                                                                                                                                                                                                                                       |
| `kick_clan_members`            | Remove players from a clan.                                                                                                                                                                                                                                  |
| `reset_clan_member_scores`     | Set the score of every member of a clan to 0 (asks for confirmation).                                                                                                                                                                                        |
| `reset_clan_rating`            | Set the rating of every clan of the label to 0 (asks for confirmation).                                                                                                                                                                                      |
| `cancel_tournament_run`        | End a tournament run with no prizes: registrations are cancelled and buy-ins are given back (asks for confirmation).                                                                                                                                         |
| `finish_tournament_run`        | End a tournament run now and pay the prizes by the current scores (asks for confirmation).                                                                                                                                                                   |
| `clone_tournament`             | Copy a tournament into a new Draft, with its prizes, games and scoring formulas unless left out.                                                                                                                                                             |
| `approve_jackpot_pot`          | Approve the win of a jackpot pot that waits for an approval, so the winner is paid (asks for confirmation).                                                                                                                                                  |
| `clone_jackpot`                | Copy a jackpot into a new Draft, with its eligible games and contribution rules unless left out.                                                                                                                                                             |
| `sport_game_add_feed_events`   | Add matches of the sports feed to a MatchX or Quiz round.                                                                                                                                                                                                    |
| `sport_game_cancel_event`      | Cancel a match or question: it gets no result (asks for confirmation).                                                                                                                                                                                       |
| `sport_game_resolve_round`     | Resolve a MatchX or Quiz round: its leaderboard becomes final and the prizes are paid (asks for confirmation).                                                                                                                                               |
| `sport_game_resolve_season`    | Resolve a MatchX or Quiz season: its leaderboard becomes final and the prizes are paid (asks for confirmation).                                                                                                                                              |
| `vibe_create`                  | Create a Vibe Studio widget, custom game, landing page or promo page from a template.                                                                                                                                                                        |
| `vibe_run`                     | Send a prompt to the Vibe Studio AI for a project. Consumes AI tokens.                                                                                                                                                                                       |
| `vibe_set_preview_user`        | Choose the player the Vibe Studio AI builds and checks a project as.                                                                                                                                                                                         |
| `vibe_cancel_run`              | Stop a Vibe Studio AI run.                                                                                                                                                                                                                                   |
| `vibe_write_files`             | Save your own code into a Vibe Studio project.                                                                                                                                                                                                               |
| `vibe_publish`                 | Put a Vibe Studio project live; returns its address and the code to place it.                                                                                                                                                                                |

**Operations on one player.** 20 more operations change one player: give a mission, points, a bonus, mini-game attempts or raffle tickets, change a level, set several state properties at once (test account, channel opt-outs, gamification control group, markers), send a form, start or stop a campaign for the player, set a tournament score, opt the player out of a jackpot, and more. Their names start with `user_`. Each one, with its parameters and an example, is on [MCP - operations on the users](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-operations-on-the-users.md). The old names `start_campaign`, `stop_campaign_for_player` and `send_form` still work. `user_set_channel_opt_out`, `user_set_test_account`, `user_set_markers` and `user_set_gamification_control_group` still work in this release, but they will be removed in a later one: use `user_set_state` instead.

To build, clone and copy campaigns with the flow and campaign operations, see [MCP - Build and copy campaigns and journeys](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-build-and-copy-campaigns-and-journeys).

## Supported entity types

The MCP server exposes 61 entity types through the unified entity tools (`entity_list`, `entity_get`, `entity_create`, `entity_update`). Every type can be listed and read. 48 types can also be created and updated. Five types can be updated but not created: media files (tags, deletion; new files are added with the `upload_media` operation) and the four kinds of Vibe Studio project (name, description, keywords; new ones are made and built with the `vibe_` operations). The other 8 types are read-only: they are there to look up and reason about, so the right configuration can be built.

| Entity Type                                                       | List | Get | Create | Update |
| ----------------------------------------------------------------- | :--: | :-: | :----: | :----: |
| **Activity Type** (`activity_type`)                               |   ✓  |  ✓  |    —   |    —   |
| **Automation Rule** (`automation_rule`)                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Avatar** (`avatar`)                                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Avatar AI Prompt** (`avatar_prompt`)                            |   ✓  |  ✓  |    ✓   |    ✓   |
| **Badge** (`badge`)                                               |   ✓  |  ✓  |    ✓   |    ✓   |
| **Badge Reward** (`badge_reward`)                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Badge Stage** (`badge_stage`)                                   |   ✓  |  ✓  |    ✓   |    ✓   |
| **Banner** (`banner`)                                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Banner Placement** (`banner_placement`)                         |   ✓  |  ✓  |    ✓   |    ✓   |
| **Bonus Template** (`bonus_template`)                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Bonus Type** (`bonus_type`)                                     |   ✓  |  ✓  |    —   |    —   |
| **Campaign** (`campaign`)                                         |   ✓  |  ✓  |    ✓   |    ✓   |
| **Clan** (`clan`)                                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Clan Tournament Member Prize** (`clan_tournament_member_prize`) |   ✓  |  ✓  |    ✓   |    ✓   |
| **Clan Tournament Prize** (`clan_tournament_prize`)               |   ✓  |  ✓  |    ✓   |    ✓   |
| **Deep Link** (`deep_link`)                                       |   ✓  |  ✓  |    ✓   |    ✓   |
| **Event Type** (`event_type`)                                     |   ✓  |  ✓  |    —   |    —   |
| **Form** (`form`)                                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Formula** (`formula`)                                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Formula Variable** (`formula_variable`)                         |   ✓  |  ✓  |    ✓   |    ✓   |
| **Game (games catalog)** (`game`)                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Inbox Resource** (`inbox`)                                      |   ✓  |  ✓  |    ✓   |    ✓   |
| **Instant Message Gateway** (`im_gateway`)                        |   ✓  |  ✓  |    —   |    —   |
| **Instant Message Resource** (`instant_message`)                  |   ✓  |  ✓  |    ✓   |    ✓   |
| **IVR Gateway** (`ivr_gateway`)                                   |   ✓  |  ✓  |    —   |    —   |
| **IVR Resource** (`ivr`)                                          |   ✓  |  ✓  |    ✓   |    ✓   |
| **Jackpot** (`jackpot`)                                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Jackpot Contribution Rule** (`jackpot_contribution_rule`)       |   ✓  |  ✓  |    ✓   |    ✓   |
| **Label Tag** (`label_tag`)                                       |   ✓  |  ✓  |    ✓   |    ✓   |
| **Leaderboard** (`leaderboard`)                                   |   ✓  |  ✓  |    ✓   |    ✓   |
| **Level** (`level`)                                               |   ✓  |  ✓  |    ✓   |    ✓   |
| **Lootbox** (`lootbox`)                                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Mail Gateway** (`mail_gateway`)                                 |   ✓  |  ✓  |    —   |    —   |
| **Mail Resource** (`mail`)                                        |   ✓  |  ✓  |    ✓   |    ✓   |
| **Media File** (`media`)                                          |   ✓  |  ✓  |    —   |    ✓   |
| **Mini-Game** (`minigame`)                                        |   ✓  |  ✓  |    ✓   |    ✓   |
| **Mini-Game Prize** (`minigame_prize`)                            |   ✓  |  ✓  |    ✓   |    ✓   |
| **Mission** (`mission`)                                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Mission Reward** (`mission_reward`)                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Mission Task** (`mission_task`)                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Popup Resource** (`popup`)                                      |   ✓  |  ✓  |    ✓   |    ✓   |
| **Prize Drop** (`prize_drop`)                                     |   ✓  |  ✓  |    ✓   |    ✓   |
| **Property** (`property`)                                         |   ✓  |  ✓  |    —   |    —   |
| **Push Resource** (`push`)                                        |   ✓  |  ✓  |    ✓   |    ✓   |
| **Raffle** (`raffle`)                                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Raffle Draw** (`raffle_draw`)                                   |   ✓  |  ✓  |    ✓   |    ✓   |
| **Raffle Prize** (`raffle_prize`)                                 |   ✓  |  ✓  |    ✓   |    ✓   |
| **Segment** (`segment`)                                           |   ✓  |  ✓  |    ✓   |    ✓   |
| **Sport Game (MatchX, Quiz)** (`sport_game`)                      |   ✓  |  ✓  |    ✓   |    ✓   |
| **Sport Game Match or Question** (`sport_game_event`)             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Sport Game Round** (`sport_game_round`)                         |   ✓  |  ✓  |    ✓   |    ✓   |
| **Store Category** (`store_category`)                             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Store Item** (`store_item`)                                     |   ✓  |  ✓  |    ✓   |    ✓   |
| **Tournament** (`tournament`)                                     |   ✓  |  ✓  |    ✓   |    ✓   |
| **Tournament Prize** (`tournament_prize`)                         |   ✓  |  ✓  |    ✓   |    ✓   |
| **Tournament Scoring Formula** (`tournament_formula`)             |   ✓  |  ✓  |    ✓   |    ✓   |
| **Vibe Studio Custom Game** (`vibe_custom_game`)                  |   ✓  |  ✓  |    —   |    ✓   |
| **Vibe Studio Landing Page** (`vibe_landing_page`)                |   ✓  |  ✓  |    —   |    ✓   |
| **Vibe Studio Promo Page** (`vibe_promo_page`)                    |   ✓  |  ✓  |    —   |    ✓   |
| **Vibe Studio Template** (`vibe_template`)                        |   ✓  |  ✓  |    —   |    —   |
| **Vibe Studio Widget** (`vibe_widget`)                            |   ✓  |  ✓  |    —   |    ✓   |

Listing media files needs a filter: a file name, a tag, or the uploader.

Deep links: your label's own deep links can be created and updated. The deep links shared by every label are read-only, and no deep link can be deleted over MCP.

Mini-games are four entity types, one for each Back-Office screen: `minigame` (Spin The Wheel, Scratch & Catch, Gift box, Treasure Hunt, Voyager, Ballanza (Plinko), Coin Flip and Custom games made in Vibe Studio), `sport_game` (MatchX and Quiz), `prize_drop` and `lootbox`. The prizes of all of them are `minigame_prize` records. A MatchX or Quiz game has its rounds (`sport_game_round`) and their matches or questions with the results (`sport_game_event`); a resolved round can no longer be changed. A new game is saved as a Draft and needs its prizes before it is activated. A prize can be removed only while the game is not Active: a prize that a player has already won is disabled and kept for the history. For a lootbox, the answer names the days left without a prize, so each one can be covered. Sport Bingo is in beta: it can be read, and it is edited in the Back-Office. Mini-games are archived, never deleted.

Formulas: a dynamic reward formula is written as its calculation text (`formula_expression`), with its named values as `formula_variable` records. `test_formula` shows what the formula would pay chosen players, and pays nothing. Tournaments and jackpots can be created and updated, with their prizes (`tournament_prize`, `clan_tournament_prize`, `clan_tournament_member_prize`) and contribution rules (`jackpot_contribution_rule`) as entity types of their own.

The brand texts and ribbons of a mission, and the brand ribbon of a tournament or a store item, are saved the same way as on their **Branding** tab in the Back-Office.

Mission tasks and badge stages take the conditions of [Dynamic Missions](https://help.smartico.ai/welcome/products/gamification-basics/missions/dynamic-missions) as the back office sets them up: the player's top 3 favorite casino games, game types, game providers, sport types, leagues or sport markets compared with the action the player makes, and the player's recommended bet or deposit amount. A task takes one comparison of each group (casino game, game type or provider; sport type or league; sport market; recommended amount), and the task's **Lock** switches keep the player's values from their first progress. The task name shows the player's values with `{{suggested_games}}`, `{{suggested_sport}}`, `{{suggested_market}}` and `{{suggested_value}}`, and the Prop-to-Prop target with `{{suggested_amount}}`. The assistant is warned when a task name uses a tag that nothing in the task fills (players would see the tag as written), and when such a comparison sits inside a group of OR conditions, where the **Lock** and the tags do not see it.

For detailed instructions on uploading creative assets and managing media files via MCP, see [MCP - How to manage images](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-how-to-manage-images.md). For account and brand configuration settings, see [MCP - label and brand settings](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-label-and-brand-settings.md).

## Frequently asked questions

**How can I test MCP operations and analytics queries without changing data or consuming AI tokens?** Use the optional `dry_run: true` parameter. On creates, updates and actions, a dry run checks the request and saves nothing: it answers "ok" (with the server's plain-language reading of what it understood, and any warnings) or what is wrong. A passed check is not a promise: the save runs more checks. On audience estimation, avatar AI prompt tests, data-warehouse SQL queries and golden queries, a dry run tells how many AI tokens the call would use, without running it and without using tokens.

**How can an AI assistant or developer report errors or missing capabilities through MCP?** The server includes a built-in `report_problem` tool that AI assistants or API scripts can call when encountering tool errors, unexpected outputs, validation rejections, or missing platform features. Problem reports are sent directly to the Smartico engineering team for review without requiring a manual support ticket. An AI reads each report at once and answers the assistant.


---

# 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-tools-and-entity-types.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.
