> 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.md). # 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. | | **Reference data (read-only)** | Look up user properties, events, and activities used to build conditions and flows. | | **Gamification & catalog (read-only)** | Look up bonus templates, missions, badges, mini-games, raffles, jackpots, levels, clans, formulas, avatars, and deep links. | | **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. {% hint style="info" %} **Segments, automation rules, campaigns, messaging templates, and label tags can be created and changed.** **Properties, events, activities, and gamification catalog types** are available to read and reason about, so the right configuration can be built — they are not edited directly. {% endhint %} #### 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."* {% hint style="info" %} **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"*. {% endhint %} ### The tools The server exposes 11 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_knowledge` | Searches the product knowledge base and returns relevant passages with source links. Read-only. | | `get_dwh_knowledge` | 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. | 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. {% hint style="info" %} **Live reference.** An always-current reference of the available operations and their parameters is in the backoffice, in the **MCP** section. Usage of every token is tracked there too, under **MCP → Usage**. {% 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. **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.}}` personalization values). | **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` | Stop a running campaign for one player engagement. | | `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_remove_node` | Archive or disable a flow step and its children. | | `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. | ### 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](#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. {% hint style="info" %} **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. {% endhint %} **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**, give it a name, and copy the token. It is shown in full only once, at creation - afterward, it is masked and can't be retrieved. Keep it private; anyone with the token can act in your label at your user's permission level. {% hint style="warning" %} 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. {% endhint %}
**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: ```bash claude mcp add --transport http smartico https://aichat-api.smartico.ai/mcp --header "Authorization: Bearer " ``` Replace: * `` 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. * `` with the MCP token you copied in Step 1. That's it - your assistant is now connected to Smartico. {% hint style="info" %} **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: ```json { "smartico": { "type": "http", "url": "https://aichat-api.smartico.ai/mcp", "headers": { "Authorization": "Bearer " } } } ``` Save the file and restart your AI client so it picks up the new connection. {% endhint %} **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.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 ` (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/`. **Example - list active real-time automation rules** ```bash curl -X POST https://aichat-api.smartico.ai/mcp \ -H "Authorization: Bearer " \ -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 } } } }' ``` {% hint style="info" %} **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`. {% endhint %} ### 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 ` (a bare token is also accepted). * If your connector can't set custom headers, put it in the URL path instead: `.../mcp/`. ### 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.** Whether you connect with OAuth or a static token, the connection belongs to a back-office user and a default label. The assistant can only do what that user is permitted to do. * **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 only action that consumes **AI tokens** is `estimate_audience` (audience estimation); it counts toward your label's monthly AI usage. Everything else — reads, creates, and updates — doesn't. ### 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. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.smartico.ai/welcome/technical-guides/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.