◾MCP Server

Smartico's MCP Server lets an AI assistant - such as Claude, or your custom AI agent - connect to your Smartico label and build real configurations for you.

Instead of clicking through builders and forms, you describe what you want in plain language, 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.

Beta feature. The MCP integration is currently in Beta. Capabilities, settings, and connection details may change as the feature evolves. We recommend trying it on non-critical configurations first and sharing feedback with your account manager.

In the current version, only Segments and Automation rules are available through the MCP.

We recommend that our clients start integrating with these two entities and lay the groundwork, while we expand functionality to cover other areas.

What is the MCP Server?

MCP stands for Model Context Protocol - an open standard that lets an external AI assistant connect to a software platform and take actions inside it on your behalf.

Smartico's MCP Server is a live service inside the Smartico platform that acts as a secure bridge between an AI assistant or your own code and your Label on the Smartico side. Once connected, the assistant understands your label's data model - the user properties, events, and activities available to you - and can create or update real configurations such as segments and automation rules, entirely through conversation.

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

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

The MCP integration currently lets an external AI assistant - or your code - work with the following parts of your label:

Area	What can be done
Segments	Create and update audience segments - translate a plain-language description into validated conditions, or edit an existing segment's logic or status. Covers both User State (state-based) and Behavioral segments.
Automation rules	Create and update real-time and scheduled automation rules.
User properties	Discover the user-state properties available in your label (deposits, game activity, bonus history, gamification progress, and more) to build accurate conditions.
Events	Look up the events that can trigger real-time automation rules.
Activities	Look up the actions an automation rule can perform.

Segments and automation rules can be created and changed. Properties, events, and activities 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."

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".

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

If your team already uses an MCP-compatible AI assistant - for example, Claude Desktop - you can connect it directly to your Smartico label and work with the tool you already know.

Before you start, 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

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. Every token is scoped to your label, so an assistant or script that uses it can only ever see and change data within your label.

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.

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

The quickest way to connect 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:

{
  "smartico": {
    "type": "http",
    "url": "https://aichat-api<N>.smartico.ai/mcp",
    "headers": {
      "Authorization": "Bearer <your-token>"
    }
  }
}

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

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 same endpoint your AI assistant connects to can be called directly from your own scripts and services. This is intended for developers who want to automate Smartico configuration programmatically, without an AI assistant in the loop. The protocol is standard JSON-RPC 2.0 over HTTP - any HTTP client works.

Endpoint and headers

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

Header	Value
Authorization	Bearer <your-token>
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.

Operations

The API exposes a small, consistent set of operations that work across every object type:

Operation	Purpose
entity_types_list	List the object types you can work with
entity_describe	Return the fields, conditions, and valid values for a given type
entity_list	List existing objects, with optional filters
entity_get	Retrieve a single object by ID
entity_create	Create a new segment or automation rule
entity_update	Update an existing segment or automation rule

The object types are segment, automation_rule, property, event_type, and activity_type. Create and update apply to segments and automation rules; the other types are read-only and exist to help you discover valid configuration values.

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 segment or rule.

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.

How a request works

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

1. You describe what you want - in plain language, or as an API call.

2. The external assistant explores your Label to find the right properties, events, or activities.

3. The configuration is validated in a safe "dry run" - no changes are made yet.

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

5. You confirm, and only then is the segment or rule saved to your label. A link to the new configuration in the backoffice is returned.

Security & permissions

• Your MCP account stays isolated. Each MCP token is scoped to a single label. An external assistant or script using your token can only see and modify data within your label - never another.

• 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 in your label, 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 is saved without confirmation. A plain-language summary (or a dry-run preview) of what will be created or changed is shown, and your explicit approval is required before anything is written.

• 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.

Usage limits

Not limited during Beta. While the MCP integration is in Beta, requests are not limited - you can use it to explore what it can do.

When the feature reaches general availability, usage will move to a requests-based model: each label will have an allowance of requests, and requests handled through the integration will draw from that allowance. Usage will be limited by the AI Tokens capacity already available in your setup (each label has 10 million AI Tokens monthly). Different types of requests will use different amounts of the tokens, and we are splitting the types of requests into 3 categories:

• general CRUD operations - like list all segments, create/update segment - will have fixed token consumption, e.g., 1 token per request.

• operations to retrieve operational and analytical data - e.g., "List all users who converted in the campaign 123". Because such requests hit our DWH, they will be calculated based on the amount of data scanned. Depending on the complexity of the request, the time period, and the amount of data, they will consume different numbers of tokens. We will provide a "dry run" option to help you estimate token usage before executing the request. Note: the same data can be retrieved using the Smartico DWH solution, so you don't need to use MCP for such types of operations

• AI models requests - we are planning to provide the MCP tool that will trigger our LLM models, for example, you may ask through the MCP, "What's the difference between automation rules and campaigns?" or "Which Smartico SDK method should be used to get a list of all tournaments via JavaScript?" Such requests will consume tokens based on the underlying LLM model.

Example of usage pattern:

• executed segments list/search - 10,000 times

• created new segments - 200

• updated existing segments - 1000

Total tokens usage: 11,200

Frequently asked questions

Do I need to know how Smartico segments and rules work to use this? No. The external assistant understands the data model and which properties exist in your label, and it guides the conversation. You just describe what you have in mind.

Can I use it without an AI assistant? Yes. The same endpoint is a standard JSON-RPC API (see Option C), so you can automate the supported operations directly from your own code.

Can the external assistant make a mistake? 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.

Which AI assistants are supported? Any AI assistant that supports the MCP standard can connect. Claude is a widely used option.

Is this the same as Smartico's other AI features? No. Smartico's other AI features focus on content generation and answering questions. The MCP integration is the feature that lets an external AI assistant - or your code - create and manage configurations such as segments and automation rules in your label.

What's coming next? Segments and automation rules are the first building blocks. Coverage will expand to more parts of the platform over time. As new capabilities are added, the same token and connection you set up today will pick them up automatically - no reconfiguration needed.