> 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-segments-management.md).

# MCP - Segments management

The Smartico Model Context Protocol (MCP) Server provides tools for discovering, constructing, modifying, and sizing audience segments. Through standardized entity operations and platform actions, external AI assistants and automated scripts can query player attributes, assemble multi-condition audience filters, validate segment logic via dry runs, and estimate audience reach before launching campaigns or automation rules.

## Overview of Segment Management Tools

Segment management is integrated into the core MCP entity framework and platform operations. Standalone segmentation tools are not required; all operations are handled through standard entity endpoints and platform actions.

| Tool / Entity          | MCP Invocation                         | What It Does                                                                      | Key Parameters                                         | Supported Actions      |
| ---------------------- | -------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------- |
| **Segment Entity**     | `entity_list`                          | Lists segments with search filters, sorting, and pagination                       | Name search, status, type, pagination, sorting         | Read                   |
| **Segment Entity**     | `entity_get`                           | Retrieves full definition, conditions, and Back-Office direct link for a segment  | Numeric segment ID                                     | Read                   |
| **Segment Entity**     | `entity_create`                        | Creates a new User State or Behavioral segment; supports pre-commit validation    | Segment name, segment type, conditions, dry run toggle | Create                 |
| **Segment Entity**     | `entity_update`                        | Modifies an existing segment's name, notes, tags, conditions, or status           | Segment ID, fields to update, dry run toggle           | Update                 |
| **Segment Schema**     | `entity_describe`                      | Returns the segment schema, valid operators, and step-by-step workflow            | Entity type (`segment`)                                | Read-only              |
| **Property Entity**    | `entity_list`, `entity_get`            | Discovers player attributes, operators, and allowed options needed for conditions | Property name search, property ID                      | Read-only              |
| **Event Type Entity**  | `entity_list`                          | Discovers event types available for behavioral segmentation                       | Entity type (`event_type`)                             | Read-only              |
| **Audience Estimator** | `exec_operation` (`estimate_audience`) | Calculates player count matching a segment or conditions; previews token costs    | Segment ID, conditions, dry run toggle                 | Analytical Calculation |
| **Reference Guides**   | `read_resource`                        | Returns syntax specifications, workflow instructions, and worked examples         | Resource URI                                           | Read-only              |

{% hint style="info" %}
**Permission Scoping:** All segment reads, creations, modifications, and audience size estimations are strictly scoped to the Back-Office user's permissions and authorized labels associated with your MCP token. To manage segments, your assigned access profile must include editor permissions for configuration entities. For profile details, see [MCP Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md).
{% endhint %}

***

## Segment Types and Evaluation Models

When creating segments via MCP, you specify the segment evaluation model. Smartico supports two writable segment types through MCP, alongside read-only template and imported types.

| Segment Type               | Evaluation Model                     | Best Used For                                                                          | Writable via MCP |
| -------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- | :--------------: |
| **User State Segment**     | Real-time memory evaluation          | Current profile state, verification status, country, VIP tier, lifetime deposit totals |        Yes       |
| **Behavioral Segment**     | Scheduled batch rebuild              | Activity over time windows (e.g., wagered over 100 EUR on Slots in the last 30 days)   |        Yes       |
| **Common Cases Segment**   | Template-based scheduled calculation | Predefined behavioral templates (e.g., users with unused mini-game attempts)           |     Read-only    |
| **Imported (CSV) Segment** | Static user list                     | Ad-hoc offline cohorts uploaded manually via CSV                                       |     Read-only    |

### User State Segments

User State segments are the default and recommended choice for most CRM targeting. Conditions evaluate the player's current profile properties and lifetime counters.

* **Real-time processing:** Whenever a player profile attribute changes or a lifetime counter increments (such as total deposits or last login timestamp), the player's segment eligibility updates automatically.
* **Property constraints:** Conditions accept profile properties (such as country, level, account balance, or total deposits). Dynamic attributes that belong to specific single event payloads (such as a single spin bet amount) are not evaluated here.
* **Lifetime counters vs. rolling periods:** Lifetime properties (such as Total Deposit Amount or Total Deposit Count) are maintained in real time. If your audience requires "players who have deposited over 500 EUR in total", use a User State segment.

For comprehensive UI configuration details, see [User State Segments](https://help.smartico.ai/welcome/products/crm-automation/segmentation/user-state-segments.md).

### Behavioral Segments

Behavioral segments target players based on historical event activity over specific time windows, optionally combined with current user profile filters.

* **Batch evaluation:** Behavioral segments are calculated periodically by a scheduled background process and stored for campaign targeting.
* **Required event binding:** Must reference an event type that maintains historical analytics tracking. Give the event by its id or by its name.
* **Time window modes:**
  * **Sliding window:** A duration looking backward from execution time (such as 30 days), with an optional lag exclusion buffer (such as 2 hours).
  * **Fixed period:** Explicit calendar window defined by start and end dates.
  * **Relative period:** Named calendar periods (such as Previous full day, Last weekend, Last full week, or Last full month), with an optional timezone offset.
* **Rebuild scheduler:** Must specify a rebuild schedule (Daily, Weekly, Monthly, Hourly, or Exact dates) and a schedule expression. Hourly rebuilds must be enabled for your account. A rebuild time at one of the busiest times of the day is saved, and the answer adds a warning that names a quieter time.
* **Event filters vs. aggregate thresholds:**
  * **Event filters:** Filters individual event records (e.g., game category equals slots). Every qualifying event must pass this filter.
  * **Aggregate thresholds:** Evaluates totals across all matching events per user. **All volume and threshold conditions belong here.** For example, the sum of Bet Amount is greater than or equal to 100 EUR, or event count is at least 3. Placing aggregate thresholds in event filters will evaluate single events and fail.

For deep architectural rules, see [Behavioral Segments](https://help.smartico.ai/welcome/products/crm-automation/segmentation/behavioral-segments.md).

{% hint style="warning" %}
**Segment Type Immutability:** A segment's type is permanent once created. You cannot convert a User State segment into a Behavioral segment, or vice versa. If an audience requires a different evaluation model, create a new segment.
{% endhint %}

***

## Discovering Properties and Operators

Before constructing segment conditions, use MCP discovery tools to find valid user properties, allowed operators, and option identifiers. Never guess property names or raw value codes.

### Step 1: Search Candidate Properties

Call `entity_list` with entity type `property`. Filter by property name using keywords to find relevant attributes:

```bash
curl -X POST https://<your-mcp-endpoint-url>/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": "property",
        "filters": {
          "property_name": "deposit"
        },
        "limit": 10
      }
    }
  }'
```

Each returned property contains:

* Numeric property ID.
* Property label and system name.
* Property data type (numeric, text, enum, multi-currency numeric, date).
* Allowed comparison operators for this property.
* Available options for small enums. For large reference sets (countries, bonuses, tags), the response indicates that `entity_get` should be called.

### Step 2: Resolve Allowed Values

For enum or referenced properties whose options are not inlined in search results, call `entity_get` using the property's numeric ID:

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "entity_get",
      "arguments": {
        "entity_type": "property",
        "id": 12
      }
    }
  }'
```

The response returns the complete list of authorized IDs and display labels. Use these exact values in your conditions.

### Multi-Currency Monetary Properties

Properties representing account monetary balances or lifetime amounts have the multi-currency numeric type. When formulating conditions on these properties:

* Specify both the amount and currency code, for example: `100 EUR`, `50 USD`, or an object with value and currency code.
* If comparing against the user's default registered currency, use `Default` (for example, `100 Default`).
* An assistant or script must never assume or default to `Default` unless explicitly requested.

***

## Listing and Inspecting Segments

### Listing Segments (`entity_list`)

Query segments across your account with flexible filtering, sorting, and pagination:

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "entity_list",
      "arguments": {
        "entity_type": "segment",
        "filters": {
          "segment_name": "VIP"
        },
        "sort": {
          "field": "id",
          "dir": "desc"
        },
        "limit": 10,
        "offset": 0
      }
    }
  }'
```

#### Available Filters

* Segment name search (partial match).
* Status filter (Active or Archived).
* Segment type filter (User State, Behavioral, Common Cases, or Imported).
* Target event filter for behavioral segments.
* Template filter for common cases segments.
* Keyword tag filter.
* Creator and modifier user filters.

#### Supported Sort Fields

Sort parameters accept field identifier and direction (`asc` or `desc`):

* Segment ID.
* Segment name.
* Estimated audience size.
* Dependent campaigns count (usage count in active campaigns and automation rules).
* Creation date.
* Last modification date.

### Fetching a Segment (`entity_get`)

Fetch a single segment by its numeric ID to inspect its conditions, notes, rebuild schedule, and Back-Office navigation link:

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "entity_get",
      "arguments": {
        "entity_type": "segment",
        "id": 1042
      }
    }
  }'
```

The response includes:

* Segment identifier and name.
* Status (Active or Archived).
* Structured condition tree.
* Human-readable summary of the condition logic.
* Cached audience size calculated during the last background reconciliation, with calculation timestamp.
* Usage metrics showing active campaign dependencies.
* Search keyword tags.
* Direct link to view the segment in the Smartico Back-Office.

***

## Creating Audience Segments

Segments can be created using standard JSON mode or TOON text mode. In JSON mode, `segment_type_id` is required: 1 = User State, 4 = Behavioral. A dry run (`dry_run: true`) is an optional check; without it, the call saves.

### Condition Structure and Grouping Rules

In JSON payloads, conditions are passed as an array of objects:

* `p`: Property name or label.
* `o`: Comparison operator (e.g., `===`, `!==`, `>`, `>=`, `<`, `<=`, `in`, `!in`, `contains`, `empty`, `!empty`).
* `v`: Comparison value. Multi-value operators accept arrays (e.g., `["DE", "AT"]`) or comma-separated strings.
* **AND Groups:** Conditions listed consecutively at the same level must all match.
* **OR Groups:** Nest conditions inside a group object:

  ```json
  {
    "p": "GROUP",
    "o": "has-any",
    "v": [
      { "p": "Country", "o": "===", "v": "DE" },
      { "p": "Country", "o": "===", "v": "AT" }
    ]
  }
  ```
* **Property-to-Property Comparison:** A numeric or monetary property can be compared directly against another property by setting a property comparison flag and an optional multiplier:\
  `{ "p": "Real Balance", "o": ">", "v": "Bonus Balance", "m": 1.5, "visp": true }`.
* **Limit:** At most 30 conditions in each list (the state conditions, the event filters and the aggregate thresholds of a Behavioral segment). A group counts the conditions inside it. Put several values of one property into one `in` condition. A longer list is refused, on a dry run too.

### Creating a User State Segment

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "entity_create",
      "arguments": {
        "entity_type": "segment",
        "dry_run": false,
        "payload": {
          "segment_name": "Active High Rollers",
          "segment_type_id": 1,
          "conditions": [
            { "p": "Total Deposit Amount", "o": ">=", "v": "1000 EUR" },
            { "p": "Days Since Last Login", "o": "<=", "v": 7 }
          ]
        }
      }
    }
  }'
```

### Optional check with Dry Run (`dry_run: true`)

A dry run is optional. The server checks condition syntax, property existence, operator compatibility, the condition limit and your account's segment limits, and answers "ok" with the conditions in words (and any warnings), or what is wrong. Nothing is saved. Without `dry_run`, the call saves the segment.

***

## Updating and Archiving Segments

The `entity_update` tool applies partial updates: only specified fields are modified, while omitted fields retain their existing values. `null` or `""` clears the notes; the name and the status cannot be cleared. The segment type cannot be changed. An update that changes nothing is answered with a question, not a write.

### Locating the Target Segment

* **By ID:** Pass the numeric segment identifier directly.
* **By Name Search:** Pass the name in `segment_name_query` (`segment_name` renames the segment). If exactly one segment matches, the update proceeds. If multiple segments match, the server returns a prompt with candidate IDs to select from.

### Updating Metadata and Tags

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "entity_update",
      "arguments": {
        "entity_type": "segment",
        "dry_run": false,
        "payload": {
          "segment_id": 1042,
          "segment_name": "Active High Rollers (Tier 1)"
        }
      }
    }
  }'
```

{% hint style="info" %}
**Tag Replacement Rule:** Supplying a list of tags replaces the segment's entire keyword set. Passing an empty list removes all tags. To retain existing tags, omit the tags field from the update payload.
{% endhint %}

### Updating Segment Conditions

When updating conditions, pass the new condition array. The update replaces the existing condition tree. An empty list (`[]`) or `null` clears the conditions: the segment then holds all users.

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "entity_update",
      "arguments": {
        "entity_type": "segment",
        "dry_run": true,
        "payload": {
          "segment_id": 1042,
          "conditions": [
            { "p": "Total Deposit Amount", "o": ">=", "v": "1500 EUR" },
            { "p": "Days Since Last Login", "o": "<=", "v": 14 }
          ]
        }
      }
    }
  }'
```

The save answers the segment id and only the fields it changed, before and after (`whole_record: true` shows the whole segment). With `dry_run: true`, the answer is only "ok" with the conditions in words, or what is wrong.

***

## Audience Size Estimation (`estimate_audience`)

The `estimate_audience` operation calculates the exact number of players currently matching an audience definition—equivalent to clicking the **Estimate Audience** button in the Back-Office campaign builder.

Use `estimate_audience` before launching campaigns or automation rules to verify that audience filters are neither overly broad nor accidentally targeting zero players.

### Input Forms

Audience estimation supports four distinct input forms passed in the operation parameters:

1. **Existing Segment:** Pass the segment identifier or segment name to calculate the audience for an established segment.
2. **Ad-hoc User State Conditions:** Pass conditions alone without a segment ID to size an audience proposal before saving it.
3. **Behavioral Criteria:** Pass historical event criteria to calculate event cohorts.
4. **Combined Segment and Extra Filters:** Pass a segment identifier alongside additional conditions to evaluate audience reach when a campaign applies secondary entry criteria on top of a base segment.

### Estimating an Existing Segment

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "exec_operation",
      "arguments": {
        "operation": "estimate_audience",
        "params": {
          "segment_id": 1042
        },
        "dry_run": false
      }
    }
  }'
```

### Estimating Ad-Hoc Conditions

```bash
curl -X POST https://<your-mcp-endpoint-url>/mcp \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -H "x-mcp-mode: json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "exec_operation",
      "arguments": {
        "operation": "estimate_audience",
        "params": {
          "conditions": [
            { "p": "Country", "o": "in", "v": ["DE", "AT"] },
            { "p": "Total Deposit Amount", "o": ">=", "v": "500 EUR" }
          ]
        },
        "dry_run": false
      }
    }
  }'
```

### Token Cost Preview (`dry_run: true`)

Audience estimations query the analytical data warehouse and consume monthly account AI tokens based on data volume scanned. Pass `dry_run: true` to validate conditions and view estimated token expenditure without executing the calculation or deducting AI tokens:

```json
{
  "operation": "estimate_audience",
  "params": { "segment_id": 1042 },
  "dry_run": true
}
```

The dry-run response returns the estimated token cost and a readable summary of conditions.

### Result Fields

When executed with `dry_run: false`, the operation returns:

* Total number of users currently matching the criteria.
* Timestamp of the data snapshot used for the calculation.
* Monthly AI tokens deducted for this calculation.

***

## Best Practices and Platform Safeguards

* **Use Lifetime Counters for Simple Aggregates:** Do not build resource-intensive Behavioral segments for basic lifetime thresholds. For requirements like "players with more than 3 deposits" or "players who registered this year", use User State segments with lifetime accumulator properties (such as Total Deposit Count or Registration Date).
* **Respect Platform Quotas:** Each account has a limit of active (not archived) segments of each kind. The default limits are:

  * Up to 400 State-based segments.
  * Up to 50 Behavioral segments.
  * Up to 50 Common cases segments.

  When a kind has reached its quota, creating a segment of that kind is refused, and so is restoring an archived one; the refusal already comes on the dry run. Archive a segment of that kind first.
* **Avoid Circular and Deep Nesting:** A segment can be used inside the conditions of another segment. A save is refused when segments would use each other in a loop (Segment A uses Segment B, which uses Segment A), or when a segment would have more than 10 nested levels: each segment used inside another and each condition group adds one. The error names the chain.
* **Keep Active Even When Not in Use:** By default, real-time evaluation for a User State segment pauses if no active campaign or automation rule references it. Enable the keep-active toggle if the segment must maintain updated player rosters continuously for external API verification or frontend checks.
* **Enable Data Warehouse Exports:** Enable external export if your reporting stack needs to query segment membership directly through data warehouse export functions.

***

## Frequently Asked Questions

### How can I build a segment that excludes bonus abusers?

Search properties for bonus abuse markers using property discovery. Once identified, formulate your condition using the inequality operator: Bonus Abuser status is false, or Bonus Abuser flag does not equal true. You can add this condition as an extra filter on any existing segment or campaign entry rule.

### Can I export individual player records or generate a CSV file of segment users using MCP?

No. The MCP segment retrieval tool returns segment metadata, condition logic, and cached audience totals, but does not output raw player lists. To export player lists from a segment:

1. In the Smartico Back-Office, navigate to the **Segments** section, open the segment, select the **Segment Users** tab, and click **Export CSV**.
2. If external export is enabled on the segment, query the segment member export table in your data warehouse via direct analytics query or export functions.

### Why does a behavioral segment with condition "Count of activities = 0" return zero players?

Behavioral segments analyze event records that were actually logged in the analytical warehouse during the specified time window. If you configure a behavioral condition such as count of deposits equals zero over the last 30 days, the calculation searches for users who have deposit records that sum to zero, rather than users who have no records at all. To target players who have not deposited in the last 30 days, create a **User State Segment** checking the last activity timestamp: Last Deposit Date days elapsed is greater than or equal to 30 days, or Last Deposit Date is empty.

### Can I convert an existing User State segment into a Behavioral segment?

No. A segment's evaluation engine and type are permanently fixed upon creation. Attempting to change a segment's type during an update is rejected. If you need a different evaluation model, create a new segment with the desired type and archive the old one.

### How do multi-currency monetary properties evaluate players?

When configuring conditions on multi-currency properties (such as deposit balances or wager amounts), specify the currency explicitly (e.g., `100 EUR`). The evaluation engine converts player balances to the target currency based on exchange rates, or verifies that the player's account currency matches. If you specify `100 Default`, the system evaluates the raw numeric amount against each player's individual registered default currency.

### Does estimating audience size consume monthly AI tokens?

Calling `estimate_audience` with `dry_run: false` queries the analytical warehouse and consumes monthly account AI tokens based on the volume of data evaluated. To see the token cost and check that your conditions compile without using monthly tokens, run `estimate_audience` with `dry_run: true` first. The dry run is free.

***

## Related Documentation

* [MCP Server](https://help.smartico.ai/welcome/technical-guides/mcp-server.md) — System overview, connection options, and supported tool catalog.
* [MCP Access Profiles](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-access-profiles.md) — Permission governance, system access tiers, and profile assignments.
* [MCP - label and brand settings](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-label-and-brand-settings.md) — Account vocabulary, brand configuration, and delivery rate limits.
* [MCP - How to manage images](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-how-to-manage-images.md) — Media asset management and CDN uploads via MCP.
* [User State Segments](https://help.smartico.ai/welcome/products/crm-automation/segmentation/user-state-segments.md) — Core mechanics and configuration of real-time user state segments.
* [Behavioral Segments](https://help.smartico.ai/welcome/products/crm-automation/segmentation/behavioral-segments.md) — Event-driven historical time-window segmentation.
* [MCP - Build and copy campaigns and journeys](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-build-and-copy-campaigns-and-journeys) — Use the segment in a campaign: build, clone and copy journeys.
* [MCP - Prompt library](https://help.smartico.ai/welcome/technical-guides/mcp-server/mcp-prompt-library) — Example prompts for segments, campaigns and data questions.


---

# 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-segments-management.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.
