MCP tools for segment groups and segments
MCP schemas for segment groups, segment values, signals, sync mappings, linked questions, and deletion cascades.
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. 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 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 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:
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:
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.
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:
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:
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:
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:
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:
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: