# MCP tools for segment groups and segments

MCP schemas for segment groups, segment values, signals, sync mappings, linked questions, and deletion cascades.

Available on the Grow, Scale, and Pro plans.

Use these MCP tools to create segment groups, edit their segments, and configure automatic rules or email-platform sync. Segment groups define an audience attribute, such as a visitor's role. Segments are its possible values. A linked question asks the visitor to choose those values. Changing a segment name does not change the visitor-facing answer label.

## MCP segment access and draft changes

Every tool accepts an optional string `project_id` and follows the [shared MCP authorization and project-selection rules](https://rightmessage.com/help/mcp-authorization-reference). There is no additional segment-specific feature check. Provider sync still depends on the connected provider and its entitlement.

Reads use the draft if one exists, otherwise the published configuration. Mutations save a draft and a snapshot of the preceding configuration. They do not publish or assign a real visitor to a segment. Sync-field lookup can read provider metadata, but it does not create provider fields or update contacts. See [publication tools](https://rightmessage.com/help/mcp-tools-publishing) to make the draft live.

An active A/B test locks its question's linked segment values, multi-select behavior, and non-sync Auto-Segment rules. Adding, replacing, renaming, or deleting those segments can therefore fail even when the tool arguments are otherwise valid. Deleting the group can fail too. End the test first. Internal group names and sync mappings remain editable.

Results are JSON payloads within MCP responses. Shared errors include missing, invalid, and inaccessible projects. Most mutation failures use `Validation error: ...` for config-schema failures or `Operation failed: ...` for other exceptions. Group creation and update instead prefix caught errors with `Failed to create segment group:` or `Failed to update segment group:`.

Examples use fictional WorkForge resources and were not executed. They show illustrative requests and results, with excerpts labeled where fields are omitted.

## Group arguments, signals, and returned fields

Group creation and update share these fields:

| Input            | Type and behavior                                                                                                              | Stored result key   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `name`           | String. Required on creation.                                                                                                  | `name`              |
| `segments`       | Array of objects with string `name` and optional string `id`. IDs omitted during an update are new segments, not name matches. | `segments`          |
| `semantic_type`  | String, such as `company_size`. Defaults to null on creation.                                                                  | `semanticType`      |
| `allow_multiple` | Boolean. Defaults to false.                                                                                                    | `isMultiWinning`    |
| `sync_platform`  | String. Provider name. Defaults to null.                                                                                       | `syncTo`            |
| `sync_field`     | String. Provider field ID or resolvable field label. Defaults to null.                                                         | `syncToCustomField` |
| `sync_mode`      | String. `field` by default, or `tag` for tag mapping.                                                                          | `syncMode`          |
| `signals`        | Array of signal objects. Defaults to `[]`; supplied updates replace the array before sync-signal maintenance.                  | `signals`           |

A group result has a `dim_` ID and the fields above, plus `favorited`, initially false. Segments have `seg_` IDs and names. Individual segment tools can also store `description`.

Each signal contains `indicates`, a segment ID; `weight`, a string; and `definition`, a LogicDefinition object. Discovery advertises weights `weak`, `moderate`, and `strong`. Automatically generated sync signals use the string `"1"`. A standard definition has `or` groups containing `and` arrays. [Condition tools](https://rightmessage.com/help/mcp-tools-conditions) document source-specific leaf arguments.

The group service wraps a flat `{"and":[...]}` in `{"or":[{"and":[...]}]}` and normalizes condition keys `source` and `type` to `$source` and `$type`. Definitions without either `and` or `or` become `{"or":[]}`. The service is not a general recursive condition rewriter, so complete discovered definitions are preferable to shorthand.

When field sync is configured, the service adds or updates per-segment sync conditions. New mapping values are empty strings, not segment names. Existing customized values are preserved. Changing between field and tag modes removes stale sync-managed conditions from the old mode. Tag-mode signals depend on existing `syncMappings`; neither group tool exposes a `sync_mappings` argument. Selecting tag mode alone does not create a tag mapping.

For structured providers, field lookup first matches the ID, then a case-insensitive label, templating token, or key. An unmatched field returns an error, including available fields where possible. Unstructured providers accept the string as supplied. If no connection exists or fetching fields fails, the service can retain the supplied string without proving that it is valid upstream.

## `create-segment-group`

Creates a group and, optionally, its linked question.

Required `name` is a string. Optional arguments are `project_id` and the shared group fields, plus:

| Argument                | Type and default                                                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_create_question`  | Boolean, false when omitted.                                                                                                          |
| `question_text`         | String. Defaults to the group name when auto-creating a question.                                                                     |
| `question_display_type` | String. Defaults to `buttons`; supported choice presentations are `buttons`, `image`, `list`, and `radio`.                            |
| `segments[].scores`     | Optional array of `{score: string, amount: number}`. Applied to the corresponding question option only when auto-creation is enabled. |

Each segment name is required and limited to 255 characters by the creation handler. Duplicate names remain separate segments. Scores are associated by input position, removed from the segment data, and passed to the linked question options. Malformed score entries are handled by the question service, not by a segment scoring field.

Returns the group object. If a question was created, `linked_question` contains its full stored object. If there are no usable segments, the group is still created and the result adds `auto_create_question_skipped: true` and `auto_create_question_reason`. `scores_skipped` appears when segment entries with supplied scores could not produce options.

Group creation and question creation are separate saves. A later question-generation failure is not a promise that the group was rolled back. A missing or malformed segment name returns the handler's validation message. Sync-field and config failures use the group-specific error prefix.

Illustrative request and result excerpt:

```json
{"name":"create-segment-group","arguments":{"name":"WorkForge role","segments":[{"name":"Operations"},{"name":"Engineering"}],"auto_create_question":true,"question_text":"Which team do you work with?"}}
```

```json
{"id":"dim_workdemo","name":"WorkForge role","isMultiWinning":false,"segments":[{"id":"seg_opsdemo","name":"Operations"},{"id":"seg_engdemo","name":"Engineering"}],"linked_question":{"id":"raq_rolequiz","text":"Which team do you work with?","dimensionId":"dim_workdemo","displayType":"buttons","options":[{"id":"rqo_opsdemo","label":"Operations","segmentId":"seg_opsdemo","conditions":{},"scores":[]},{"id":"rqo_engdemo","label":"Engineering","segmentId":"seg_engdemo","conditions":{},"scores":[]}]}}
```

The complete objects include the remaining defaulted group and question fields. Neither the question nor the group is placed into a flow automatically.

## `list-segment-groups`

Returns compact group summaries. Its only argument is optional string `project_id`. Each row contains `id`, `name`, `segmentCount`, `segments: [{id, name}]`, `hasQuestion`, and `syncTo`.

Here `syncTo` is a readable `provider: field` summary or null, not the raw provider-only config value. Signals are omitted. There is no pagination. No configuration mutation occurs. Shared access errors apply.

Illustrative request and result:

```json
{"name":"list-segment-groups","arguments":{}}
```

```json
[{"id":"dim_workdemo","name":"WorkForge role","segmentCount":2,"segments":[{"id":"seg_opsdemo","name":"Operations"},{"id":"seg_engdemo","name":"Engineering"}],"hasQuestion":true,"syncTo":null}]
```

## `get-segment-group`

Returns one full group with read annotations. Arguments are optional string `project_id` and required string `segment_group_id`.

The result adds `linkedQuestion`, either null or `{id, text, displayType, optionCount}`. It also adds `syncSummary`, optional `signalDescriptions` when signals exist, and resolved resource-name fields. The underlying `signals` remain present. The question's complete option settings require [question tools](https://rightmessage.com/help/mcp-tools-questions).

Missing ID returns `segment_group_id is required.` Unknown IDs return `Segment group 'ID' not found.` This read does not change configuration.

Illustrative request and result excerpt:

```json
{"name":"get-segment-group","arguments":{"segment_group_id":"dim_workdemo"}}
```

```json
{"id":"dim_workdemo","name":"WorkForge role","linkedQuestion":{"id":"raq_rolequiz","text":"Which team do you work with?","displayType":"buttons","optionCount":2},"syncSummary":null,"signals":[]}
```

## `update-segment-group`

Updates a draft group. Required string `segment_group_id` selects it. Optional arguments are `project_id` and all shared group fields. Omitted or null values retain the current values. The handler allows an ID-only call, which can still run sync-signal maintenance.

Returns the full updated group. `segments` and `signals` replace their respective arrays, not individual entries. IDs in a replacement segment array preserve identity; entries without IDs receive new ones. This operation does not automatically update linked question labels or promise the individual segment deletion cascade for omitted entries.

Missing ID returns `segment_group_id is required.` Unknown IDs return `Segment group 'ID' not found.` Sync-resolution and validation failures use `Failed to update segment group: ...`.

Illustrative request and result excerpt:

```json
{"name":"update-segment-group","arguments":{"segment_group_id":"dim_workdemo","allow_multiple":true}}
```

```json
{"id":"dim_workdemo","name":"WorkForge role","isMultiWinning":true,"segments":[{"id":"seg_opsdemo","name":"Operations"},{"id":"seg_engdemo","name":"Engineering"}]}
```

## `delete-segment-group`

Deletes a group and its segments from the draft. Arguments are optional string `project_id` and required string `segment_group_id`.

The cascade removes linked library questions and phrases linked to the dimension. It clears `segmentGroupId` on matching `sg` flow nodes; it does not remove those node containers. Previous-answer references to a linked question block deletion. Other references remain subject to config validation; this is not a guarantee that every audience rule or form field is repaired.

Returns `{"deleted":true,"segment_group_id":"ID"}`. Missing ID returns `segment_group_id is required.` Unknown IDs return `Operation failed: Segment group 'ID' not found.` Shared validation errors apply.

Illustrative request and result for an unreferenced group:

```json
{"name":"delete-segment-group","arguments":{"segment_group_id":"dim_unused01"}}
```

```json
{"deleted":true,"segment_group_id":"dim_unused01"}
```

## `create-segment`

Appends one segment to an existing group. Required string arguments are `segment_group_id` and `name`. Optional arguments are string `project_id` and string `description`. There is no score, signal, or question-option argument.

Returns `{id, name}` plus `description` when supplied. It also inserts an empty branch before the final branch in each branching `sg` flow node that references the group. It does not create a linked question answer option. That requires `create-question-option`.

Missing required values return `segment_group_id is required.` or `name is required.` A missing group returns `Operation failed: Segment group not found: ID`. Config validation can also prevent saving.

Illustrative request and result:

```json
{"name":"create-segment","arguments":{"segment_group_id":"dim_workdemo","name":"Customer success","description":"WorkForge customer success teams"}}
```

```json
{"id":"seg_success1","name":"Customer success","description":"WorkForge customer success teams"}
```

## `update-segment`

Changes a segment's name or description. Required string `segment_id` selects it across all groups. Optional string arguments are `project_id`, `name`, and `description`. At least one of name or description must be non-null. An empty string is a supplied value; null does not clear the field.

Returns the updated segment object. It does not change question-option labels or regenerate group sync signals. Signals belong to the parent group.

Missing ID returns `segment_id is required.` An empty update returns `At least one of name or description must be provided.` A supplied `signals` parameter is explicitly rejected with guidance to use `update-segment-group`. An unknown segment returns `Operation failed: Segment not found: ID`.

Illustrative request and result:

```json
{"name":"update-segment","arguments":{"segment_id":"seg_success1","name":"Customer experience"}}
```

```json
{"id":"seg_success1","name":"Customer experience","description":"WorkForge customer success teams"}
```

## `delete-segment`

Removes one segment from its group. Arguments are optional string `project_id` and required string `segment_id`.

The draft cascade removes matching question options, phrase-map entries, split branches referencing that segment, and campaign variant rules referencing it. Removing a split entry also removes the nodes inside that branch. The service also clears recognized legacy `hasSegment` conditions in yes/no nodes; it does not promise to rewrite every LogicDefinition reference.

Removing a campaign rule can broaden the remaining audience. A deletion should not be treated as a harmless label change.

Returns `{"deleted":true,"segment_id":"ID"}`. Missing ID returns `segment_id is required.` An unknown segment returns `Operation failed: Segment not found: ID`. Shared config validation errors apply. All cascades remain draft-only until publication.

Illustrative request and result:

```json
{"name":"delete-segment","arguments":{"segment_id":"seg_success1"}}
```

```json
{"deleted":true,"segment_id":"seg_success1"}
```