◾MCP Server

The Smartico MCP Server lets an AI assistant — or any program you write — work with your Smartico back-office through a single, standardized interface. Ask it to build a segment, draft a campaign, look up how a feature works, or discover which analytics tables answer a question, all in plain language or with simple API calls.

Instead of clicking through builders and forms, you describe what you want, review the assistant's proposal, and confirm. The assistant does the setup.

The same service is also a direct API: the endpoint an AI assistant connects to can be called directly from your own scripts and backend services, with no AI assistant or special library required.

What is the MCP Server?

MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external systems in a structured, safe way. The Smartico MCP Server exposes your platform as a set of tools the assistant can call: it can discover what object types exist, read your existing records, create and update campaigns and segments, run platform operations, and search the product knowledge base.

Every call runs against one label (environment) and respects the permissions of the back-office user the token belongs to — the assistant can only see and change what that user could change in the UI.

Think of it as giving an AI assistant a "Smartico plug-in": it knows what exists in your label, understands how Smartico's tools fit together, and can build and save configurations for you — always with your confirmation. And because the same endpoint speaks a standard protocol over HTTP, developers can call it directly as an API to automate the same operations programmatically.

Why it exists

• Talk to your platform in natural language. Describe the segment or campaign you want; the assistant assembles it using the same rules the back-office enforces.

• Automate repetitive work. Clone campaigns, bulk-update templates, or estimate audiences from a script.

• Keep humans in control. Every write can be previewed with dry_run before it commits, and every action is scoped to your token's label and permissions.

• One interface for everything. The same protocol covers messaging, segmentation, campaigns, gamification look-ups, product knowledge, and analytics schema discovery.

Setting up a precise audience or a multi-step automation in the back-office takes time and platform know-how: finding the right user properties, choosing the correct operators and values, and combining conditions so the logic is exactly right.

Consider a segment like:

Players whose total deposits are over €100, whose favourite product is Casino, and who haven't logged in for the last 7 days.

Building that by hand means several screens and careful attention to detail. With the MCP integration, you describe it in one sentence; the AI assistant finds the right properties in your label, assembles the logic, validates it, and shows you a plain-language summary to approve before anything is saved.

The result: routine configuration work that used to take minutes (and platform expertise) becomes a short conversation — or a single API call — while you stay in full control of what gets created.

What you can do today

Area	What you can do
Segments	Create and update audience segments with user-state and behavioural logic; list, read, estimate their size.
Automation rules	Create and update real-time and scheduled automation rules.
Campaigns	Create and update campaigns, edit their flow (steps, branches, delays, communications), manage tags and stop/convert rules, clone, start, stop, and change speed.
Messaging templates	Create and update Push, Email, Popup, Inbox, IVR, and Instant-message templates.
Label tags	Create and update label tags.
Banners & placements	Create and update banners and banner placements; link or unlink banner variations to placements.
Reference data (read-only)	Look up user properties, events, and activities used to build conditions and flows.
Bonus templates	Create and update bonus templates; look up bonus types and dynamic configuration options.
Gamification & catalog	Look up missions, badges, mini-games, raffles, jackpots, levels, clans, tournaments, and deep links. Avatars, avatar AI prompts, dynamic reward formulas, and tournament scoring formulas can be created and updated.
Product knowledge	Search the Smartico help articles, academy, FAQ, and public API docs and get cited passages.
Analytics data knowledge	Discover which data-warehouse tables answer a question, with their columns, joins, and example queries.

Read-only object types can be listed, fetched, and described, but not created or updated through MCP.

Segments, automation rules, campaigns, messaging templates, bonus templates, formulas (dynamic reward and tournament scoring), label tags, banners, banner placements, forms, avatars, and avatar AI prompts can be created and changed. Properties, events, activities, communication gateways (email, SMS/instant messaging, IVR), and gamification catalog types (missions, badges, levels, games, tournaments) are available to read and reason about, so the right configuration can be built — they are not edited directly.

Example prompts

• "Create a segment of players at the Gold gamification level with more than 5 total deposits who haven't logged in for 7 days."

• "Build a high-value churning segment: total deposits over €500 and last login more than 30 days ago."

• "Archive the segment named 'Summer Promo Q3' - it's no longer needed."

• "Set up a real-time rule that gives 10 diamonds when a user makes their first deposit."

• "Update the 'Active Sports Bettors' rule to also exclude users flagged as bonus abusers."

• "Draft a campaign that emails Gold-level players who haven't logged in for 7 days, then follow up with a push after 24 hours."

• "Clone campaign 12345 into a new draft and show me the flow before I start it."

A note on how segments work. Segments are built from a user's current state - lifetime totals (e.g., total deposit count, total deposit amount), last-activity dates (e.g., last login, last deposit), and current attributes (e.g., gamification level, favorite product). Describe your audience using these, and your assistant will build it reliably.

Rolling time-window conditions, such as "deposited 5 times this month" or "claimed a bonus this week," need to be expressed with the same intent - lifetime total plus a last-activity date instead - for example, "more than 5 total deposits and last deposit within the last 30 days".

The tools

The server exposes 13 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. 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.
entity_get	Fetches a single record by id.
entity_create	Creates a record. Pass dry_run: true to validate and preview without saving.
entity_update	Updates a record. Pass dry_run: true to see a before/after diff without saving.
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). Read-only.
exec_sql	Executes a single read-only SQL query against the analytics data warehouse, returning rows as CSV with column metadata and cost estimates. Consumes AI tokens based on data scanned. Supports dry_run.
report_problem	Reports a tool error, unexpected result, validation rejection, or missing capability directly to the Smartico team. 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 for full details on tool grant groupings.

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.

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.

Read-only (via read_operation):

Operation	Purpose
flow_get	Read a campaign's flow as nodes/edges, a text tree, and a diagram.
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.
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.
get_widget_settings	Read gamification widget settings (visual theme, section display, header counters) for real or test users at the account or brand level.

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).
start_campaign	Start a campaign for one player or a segment (up to 50 players).
stop_campaign_for_player	Stop a running campaign for one player engagement.
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.
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.
flow_copy_node	Copy or move a step and its subtree under another parent.
flow_annotation	Add, update, delete, or list flow canvas notes.
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.
send_form	Send an active form to a player by user ID or external ID using the account's personal-form campaign.
upload_media	Upload an image, video, audio, or document file to the media library from a public HTTPS URL or base64 data.
test_avatar_prompt	Test an avatar AI prompt on an avatar to generate a preview image before saving. Consumes AI tokens.

Supported entity types

The MCP server exposes 35 entity types through the unified entity tools (entity_list, entity_get, entity_create, entity_update). All entity types support listing and retrieving individual records, while configuration entities also support creation and modification.

Entity Type	List	Get	Create	Update
Activity Type (activity_type)	✓	✓	—	—
Automation Rule (automation_rule)	✓	✓	✓	✓
Avatar (avatar)	✓	✓	✓	✓
Avatar AI Prompt (avatar_prompt)	✓	✓	✓	✓
Badge (badge)	✓	✓	—	—
Banner (banner)	✓	✓	✓	✓
Banner Placement (banner_placement)	✓	✓	✓	✓
Bonus Template (bonus_template)	✓	✓	✓	✓
Bonus Type (bonus_type)	✓	✓	—	—
Campaign (campaign)	✓	✓	✓	✓
Clan (clan)	✓	✓	—	—
Deep Link (deep_link)	✓	✓	—	—
Event Type (event_type)	✓	✓	—	—
Form (form)	✓	✓	✓	✓
Formula (formula)	✓	✓	✓	✓
Inbox Resource (inbox)	✓	✓	✓	✓
Instant Message Gateway (im_gateway)	✓	✓	—	—
Instant Message Resource (instant_message)	✓	✓	✓	✓
IVR Gateway (ivr_gateway)	✓	✓	—	—
IVR Resource (ivr)	✓	✓	✓	✓
Jackpot (jackpot)	✓	✓	—	—
Label Tag (label_tag)	✓	✓	✓	✓
Level (level)	✓	✓	—	—
Mail Gateway (mail_gateway)	✓	✓	—	—
Mail Resource (mail)	✓	✓	✓	✓
Media File (media)	✓	✓	—	✓
Mini-Game (minigame)	✓	✓	—	—
Mission (mission)	✓	✓	—	—
Popup Resource (popup)	✓	✓	✓	✓
Property (property)	✓	✓	—	—
Push Resource (push)	✓	✓	✓	✓
Raffle (raffle)	✓	✓	—	—
Segment (segment)	✓	✓	✓	✓
Tournament (tournament)	✓	✓	—	—
Tournament Scoring Formula (tournament_formula)	✓	✓	✓	✓

Two ways to use it

You can use the MCP Server with your own external AI assistant or as a direct API from your own code.

Option A — Connect your own AI assistant

Add Smartico as an MCP connector in your assistant, using the endpoint below, and start a conversation — the assistant discovers the available tools automatically. There are two ways to authenticate the connection (see Authentication):

• Sign in with Smartico (OAuth) — the recommended option. Point the assistant at the MCP endpoint; it opens a Smartico sign-in page where you log in and choose which label(s) to grant, then connects automatically. Nothing to copy or paste.

• Static MCP token — create a token in the back-office and add it to the connector.

Before you start with a static token, you need back-office access to obtain your label's MCP connection token. If you can't find it, contact your Smartico account manager.

Step 1 - Create an MCP token (static-token path)

Generate a token in the backoffice. You can create more than one - for example, a separate token per tool, integration, or teammate - and give each a recognizable name. A token may be scoped to one or more labels your user can access.

1. Log in to the Smartico backoffice.

2. Open the MCP section and go to Access tokens.

3. Click Create token, enter a name, choose an Access profile (such as MCP Viewer, MCP Editor, MCP Analyst, or MCP Full access), select the authorized labels, and copy the token. It is shown in full only once at creation — afterward, it is masked and cannot be retrieved. For details on privilege tiers, see MCP Access Profiles.

Treat your MCP token like a password. Don't share it or paste it into untrusted tools. If it's ever exposed, deactivate it from the Access tokens screen and generate a new one.

Step 2 - Add Smartico to your AI assistant

If your assistant supports OAuth, point it at the MCP endpoint and complete Sign in with Smartico — no token to paste.

If you are using a static token, the quickest way to connect (for example in Claude Desktop) is to run a single command. In a terminal, run:

claude mcp add --transport http smartico https://aichat-api<N>.smartico.ai/mcp --header "Authorization: Bearer <your-token>"

Replace:

• <N> with your Smartico environment number - for example aichat-api2.smartico.ai. If you're unsure which environment you're on, check with your account manager.

• <your-token> with the MCP token you copied in Step 1.

That's it - your assistant is now connected to Smartico.

Prefer editing the config file? Instead of the command, you can add the same entry to your AI client's MCP configuration file by hand:

{
  "mcpServers": {
    "smartico": {
      "url": "https://<your-mcp-endpoint-url>/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Save the file and restart your AI client so it picks up the new connection.

Connecting with web AI assistants (Claude, ChatGPT custom connectors): In your AI client's settings, open Connectors → Add custom connector and enter your environment connector URL with the token in the URL path: .../mcp/<your-token>.

Step 3 - Start a conversation

Once connected, just describe what you want. For example:

"Connect to Smartico and create a segment of users who haven't deposited in the past 14 days but logged in at least once."

The AI assistant automatically discovers the right properties in your label, assembles the configuration, validates it, and asks you to confirm before saving.

Option B — Call it directly as an API

The server speaks JSON-RPC 2.0 over HTTP. Send a POST to the /mcp endpoint with your token; clients that stream responses also open a GET connection to the same endpoint. Any HTTP client works — no special library required.

Endpoint

https://aichat-api<N>.smartico.ai/mcp

Use the URL for your environment (your Smartico contact can confirm it). Example: aichat-api2.smartico.ai.

Headers

Header	Value
Authorization	Bearer <your-token> (a bare token is also accepted)
Content-Type	application/json
x-mcp-mode	json for programmatic clients (returns standard JSON). The default, toon, is a compact format optimised for AI assistants.

If your connector can't set custom headers, put the token in the URL path instead: .../mcp/<your-token>.

Example - list active real-time automation rules

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": "entity_list",
      "arguments": {
        "entity_type": "automation_rule",
        "filters": { "rule_type_id": 1, "is_active": true },
        "limit": 10
      }
    }
  }'

Preview before you commit. entity_create and entity_update accept a dry_run option. With dry_run: true the request is validated and a preview of exactly what would be built is returned - nothing is saved. With dry_run: false the change is committed. We recommend a dry run before creating or updating any record. exec_operation also supports dry_run.

Authentication

You can connect in one of two ways.

Sign in with Smartico (OAuth)

For AI assistants that support OAuth, this is the easiest and most secure option — there's no token to create, copy, or store.

1. Add the Smartico MCP endpoint to your assistant.

2. The assistant discovers Smartico's OAuth configuration automatically and opens a Smartico sign-in page in your browser.

3. You log in and choose which label(s) the connection may access.

4. On approval, the assistant is connected. It refreshes its own access automatically, so you don't have to reconnect.

Behind the scenes this maps to your back-office user and issues a personal access scoped to the labels you approved — the same permission model as a token. It uses standard OAuth 2.0, so any OAuth-capable MCP client works without manual configuration.

Static MCP token

Create an MCP token in the Smartico back-office (see Step 1 under Option A) and give it to your connector or script. Treat it like a password — it grants access at your user's permission level.

• Pass it in the Authorization header as Bearer <your-token> (a bare token is also accepted).

• If your connector can't set custom headers, put it in the URL path instead: .../mcp/<your-token>.

How a request works

Whichever method you use, the flow is designed so that nothing is saved without your approval:

1. You (or your assistant) call a tool with its arguments — in plain language, or as an API call.

2. The server authenticates your token and resolves it to a label. If you passed an optional label_id, it must be one your token is authorized for; otherwise the token's default label is used.

3. The assistant (or your code) explores your label to find the right properties, events, activities, or other records.

4. The tool runs against your back-office, applying the same validation the UI does. Writes can be previewed with dry_run: true — no changes are made yet.

5. You review a plain-language summary (or the dry-run preview) of exactly what will be created or changed.

6. You confirm, and only then is the change saved. A link to the affected record in the backoffice is returned.

Security & permissions

• Access = user + label + access profile. Whether you connect with OAuth or a static token, the connection is scoped to an access profile (such as MCP Viewer, Editor, Analyst, or Full access) and a set of authorized labels. For comprehensive profile configuration details, see MCP Access Profiles.

• Per-label authorization. A token may be scoped to several labels. Any tool call can target one of them with the optional label_id argument; a label the token isn't authorized for is rejected.

• Same rules as the UI. Creates and updates go through the same validation as the back-office forms, so MCP can't write data the platform would reject.

• Create and name multiple tokens. Issue separate tokens per tool, integration, or teammate, each with its own name, so you can track and revoke them independently. Anyone with a token can act at your user's permission level, so manage them accordingly.

• Copy a token once. The full token is shown only at creation and is masked afterward — store it securely, and generate a new one if it's lost.

• Nothing changes without approval. Reference and catalog types and the knowledge tools can't change anything. Actions that write — entity_create, entity_update, and exec_operation — aren't auto-approved by assistants, so a person confirms them. Use dry_run to preview before committing.

• Tokens can be revoked at any time. Deactivate a token from the Access tokens screen, and access is lost immediately.

• Changes are attributed. Configurations created or edited through the integration are recorded under a dedicated AI/API user in your label, so integration changes are easy to distinguish from manual changes in your change history.

• Usage is logged. Every operation is recorded and visible in the backoffice under MCP → Usage, so label activity can be reviewed and audited per token and per operation.

To see the labels a token can use, read the resource smartico://labels.

Usage limits

• MCP tool calls are not rate-limited on their own.

• The actions that consume AI tokens are audience estimation and data-warehouse SQL queries; they count toward your label's monthly AI usage based on the volume of data scanned. Everything else — reference reads, entity discovery, creates, and updates — does not consume AI tokens.

Frequently asked questions

Do I need to know how Smartico segments and rules work to use this? It helps, but it isn't required. You describe what you want in plain language, and the assistant uses entity_describe and the built-in guides to assemble it with the same rules the back-office enforces. Use dry_run to preview before anything is saved.

Can I use it without an AI assistant? Yes. The server is a standard JSON-RPC 2.0 API — you can call it directly from your own scripts or integrations with an MCP token (see Option B).

Can the external assistant make a mistake? The assistant only acts within your user's permissions and label, and every create or update can be previewed with dry_run before it commits. The dry-run validation catches structural errors before anything is saved, and you review a plain-language summary before confirming. If something looks off, just say so in the chat — the assistant will revise it. Riskier actions live behind exec_operation, which assistants don't auto-approve — so you stay in control of anything that changes state.

Which AI assistants are supported? Any MCP-compatible client. Assistants that support OAuth can connect with Sign in with Smartico; others can use a static MCP token in the connector settings. Claude is a widely used option.

Is this the same as Smartico's other AI features? No. This is a connector that lets your own AI assistant operate your back-office. It's separate from the in-product AI assistants, though it can search the same product knowledge base.

What's coming next? Coverage keeps expanding across the platform, and new tools and object types are added regularly. Whatever you connect today keeps up automatically — the same token and connection pick up new capabilities as they ship, with no reconfiguration. If there's a workflow you'd like exposed through MCP, let your Smartico contact know.

Where do I generate and manage MCP access tokens? In the Smartico back-office, navigate to MCP → Access tokens and click Create. You can assign a descriptive name and select which label(s) the token can access. The full token is displayed only once upon creation; make sure to copy and store it securely.

How can I test MCP operations and analytics queries without changing data or consuming AI tokens? Use the dry_run: true parameter. On entity creation and updates, dry runs validate the payload and return a before/after preview without committing changes. On audience estimation and data-warehouse SQL queries, dry runs validate the request and return estimated query size without deducting monthly AI tokens.

What is the difference between MCP tokens and the Public API? MCP is built for platform configuration (creating segments, campaigns, rules, templates) and conversational AI tooling. For high-volume player event tracking, real-time gaming transactions, or front-end widget integration, use the Smartico Public API and front-end SDKs.

What should I do if the MCP section is not visible in my back-office menu? Access to the MCP menu (Access tokens, Playground, Usage) requires the feature to be enabled for your label and granted to your user permission group. If the MCP section is missing from your navigation menu, contact your Smartico account manager or support team to enable MCP access for your account.

How does data warehouse SQL execution work, and what are its safety rules? You can run BigQuery Standard SQL SELECT queries against your analytics data warehouse using exec_sql. The tool enforces read-only execution (all write and DDL operations are rejected), restricts queries to your authorized label dataset, and returns rows as CSV (up to 1,000 rows). Pass dry_run: true to check syntax and view estimated data scan sizes before consuming monthly AI tokens.

Is there an additional fee to use the MCP server? No. Access to the MCP server endpoint and configuration tools is included with your Smartico platform license. Standard entity discovery, reads, creates, and updates do not incur extra costs. Only audience estimation calculations and data-warehouse SQL queries consume monthly AI token allocation based on the volume of data scanned.

How do I know which environment endpoint URL to use? The environment number in your connection URL matches the environment hosting your Smartico back-office (for example, environment 6 uses the environment 6 AI API endpoint). You can find your exact endpoint URL and pre-formatted configuration commands in the back-office under MCP → Access tokens after creating a token.

Can team members connect their own AI assistant accounts individually? Yes. Using OAuth (Sign in with Smartico), each team member logs in with their own back-office credentials and selects their authorized labels. All actions are scoped to that user's permissions and MCP access profile, and audit logs attribute changes to the individual user.

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.

Do back-office IP allowlist restrictions apply to MCP connections? Yes. If your account enforces IP allowlists, requests made with static service tokens or personal tokens from technical scripts and CLI tools must originate from an authorized IP address. Direct web-based AI connectors (such as Claude web custom connectors) are routed through verified gateway channels.

What happens to active MCP connections if a user's permissions or profile change? If a user is deactivated in the back-office, all associated personal tokens and OAuth connections are immediately blocked. If a user's MCP access profile is modified, active personal tokens are automatically revoked, requiring the user to re-authenticate via Sign in with Smartico to receive updated permissions.