Usertour MCP Server

Soft-delete an event definition: it leaves lists and pickers, recorded events keep resolving it, and `restore_event_definition` — or creating or tracking the same codeName again — brings it back. REFUSED (E1030) while live or draft content uses it (a tracker that fires it, or an event condition) — the error names them; `list_references(kind: "event")` shows where. Having recorded events does not block it.

Soft-delete a locale. It stops being offered and delivered AT ONCE — in every environment, users of that language see the source language — but the translations it holds on every version are kept, so `restore_localization` (or creating the same `code` again) brings them all back. The default locale cannot be deleted. To switch ONE content's translation off instead, use `update_version_localization` with `enabled: false`.

Soft-delete a segment: it leaves lists but keeps its members, and `restore_segment` brings it back. REFUSED (E1043) while live or draft content or a theme variation still uses it — the error names them; `list_references(kind: "segment")` shows where. An integration sync feeding it stops (restore does not bring the sync back).

Delete a session — PERMANENT, with three distinct consequences: (1) the session record is gone (no restore_session exists); (2) its recorded answers vanish from question analytics irreversibly — deleting "test" sessions rewrites real response counts; (3) attribute values the session wrote onto the user via bindAttribute REMAIN on the user — clearing those is a separate user-attribute update, or the user profile will contradict the survey analytics. With multiple environments you must pass `environmentId` (single-env projects default).

Soft-delete a theme: it leaves lists but historical versions keep it, and `restore_theme` brings it back. Rejected for the project default / system themes, and while any live or draft version still uses the theme (switch that content to another theme first — see update_content_version themeId). Historical versions do not block deletion.

Delete an end-user by external id. With multiple environments you must pass `environmentId` (single-env projects default).

Delete an outbound webhook endpoint and its delivery log.

Answer "why isn't my content showing?" — the #1 targeting question. Requires BOTH `user:read` (it returns end-user data, environment-fenced) and `content:read` (it reads the content config). Returns a gate checklist drawn from: published / identified / start_rules / frequency / single_session / hidden / active_session / target (announcements get their own set: scheduled / rc_reachability / start_rules-as-audience-filter / seen). Gates appear CONDITIONALLY — only the ones that apply to this content type and state (e.g. active_session only when a session is currently live; target only for launch…

The per-USER panorama — one call instead of a per-content diagnose whose conclusions shift as you go. Requires BOTH `user:read` (end-user data, environment-fenced) and `content:read` (it reads each content's config). Sorts everything published in the environment into: `showing` (with how — resumed session / won the auto-start race / feed), `queued` (eligible but behind the slot holder or a higher-priority winner — the race is settled with the SAME selectors the runtime uses, so the winner/loser verdicts cannot drift), `blocked` (ONE most-relevant gate per content), and `browser_dependent` (und…

Duplicate a piece of content into a fresh content. Copies the source's current EDITED DRAFT — which may DIFFER from what is published/live (if the source has an unpublished or diverged draft you get the draft, NOT production); the copy starts UNPUBLISHED and carries no version history. Optionally set a `name`. Content is project-level — use publish_content to make the copy live in an environment. Returns the new content.

Copy a theme — settings AND variations verbatim — into a fresh non-default theme (the builder's duplicate dialog path). The way to derive "same as X except …": duplicate, then update_theme the copy. System themes may be duplicated. Returns the new theme.

End an in-progress session (endReason admin_ended). Idempotent: ending an already-ended session is a no-op that returns it unchanged — the original endedAt/endReason are preserved, not overwritten. Tracker sessions have no end semantics and refuse with E1017. With multiple environments you must pass `environmentId` (single-env projects default). Returns the ended session.

Get a single attribute definition by id.

Read this BEFORE authoring content. Called with no args it returns the core — the create→update→validate→publish lifecycle and what each type must have to publish — plus a table of contents (per section: name, one-line summary, which content types it applies to, approx tokens). Then fetch the sections your task touches in ONE array call, e.g. `section: ["themes", "conditions", "start-rules"]` — pick the rows whose `appliesTo` covers your content type (`get_content_schema` also names them as `guideSections`); `sdk` / `host-dependencies` can wait until you verify. Fetching every section at once …

Get a company by its external id. `expand` inlines users / memberships. A single-environment token targets its env; with multiple, pass `environmentId`.

Get a single piece of Usertour content by its id. Optionally `expand` the "editedVersion" and/or "publishedVersion" objects inline. Publish state is per-environment under `environments[]`. Includes `editorUrl` — a dashboard deep link a human can open to review the content (when the server knows its dashboard URL).

How is this content performing? The response shape follows the content type: flows report starts + completions and a per-step funnel with tooltip-target-missing counts (the selector-health signal); checklists starts + completions (= every visible task done), panel opens (the per-task rate denominator — completion does NOT require opening, so only click-completed tasks form a true funnel) and per-task rows; launchers seen + activations; banners seen + dismissals; resource centers opens + block clicks; trackers users + occurrences of the tracked event; announcements seen counts (once per user). …

Survey results for this content, aggregated per question: answer distribution (choice questions list EVERY configured option, count 0 when unchosen), NPS score with promoter/passive/detractor shares, rating averages — each with a rolling-window daily series: byDay rows are CUMULATIVE over the trailing `rollingWindowDays` (echoed per series), NOT per-day increments like get_content_analytics byDay. Defaults to the last 30 days, UTC. Two consequences worth stating before quoting a number: (1) a rising byDay `score` is a running average catching up, NOT a per-period trend — for a genuine week-ove…

Return the JSON Schema for the body you write to `update_content_version` for a content type: `flow` → the `steps` array item; checklist / launcher / banner / tracker / announcement / resource-center → the `data` object. The `data` arg is polymorphic so its schema is NOT on the tool itself — fetch it here before authoring a non-flow type. Authoring SEVERAL types? Pass an array — the shared vocabulary (conditions / actions / blocks, ~90% of each schema) is then emitted once in `$defs` instead of once per call. The response also carries `capabilities`: which startRules knobs (frequency / priorit…

Get a content version by id. `expand: ["steps"]` inlines the decompiled steps — read these before calling `update_content_version`. Also supports "data", "questions" and "localizations" (per-locale translation status: enabled / missing / outdated).

Get a single environment by id.

Get a single event definition by id (includes its attached attribute codeNames).

Get a segment by id (condition segments inline their conditions). `expand: ["memberCount"]` adds how many users/companies the segment holds in ONE environment (members are env-scoped; the count uses the same filter list_users/list_companies apply for segmentId, so they always agree).

Get a content session by id. `expand` inlines content / user / company / version / answers. A single-environment token targets its env; with multiple, pass `environmentId`.

Get a single theme by id. `expand: ["settings"]` reads the stored style INTENT (colors, fonts, sizes, …) — Auto-capable colors come back as the literal "Auto", unresolved; read this to round-trip edits. `expand: ["resolvedSettings"]` reads the render truth instead: the same shape with every "Auto" replaced by the concrete color the renderer derives — use it to verify what end users actually see. A color group carries exactly the keys it takes (a text color has no `background`, a fill no `color`; get_theme_schema is the authority). `expand: ["variations"]` for conditional variations. Base field…

Return the JSON Schema of the writable theme `settings` — the fields you can pass to create_theme / update_theme and their ranges/enums. The tool exposes `settings` as a generic object, so fetch the shape here before theming. Settings is field-merged onto the current settings. Each color group accepts exactly the keys it renders (a text color has no `background`, a fill no `color` — the schema is the authority). Settings are pure INTENT: write a hex to customize an Auto-capable color, or the literal "Auto" (the default for hover/active) to let the renderer derive it; read what "Auto" resolves …

Which content is being used, and by whom — every content in ONE ranked table, no contentId needed upfront. Per row: `activity` + `activityKind` (sessions for flow/checklist/launcher/banner/resource-center; events for tracker; seen for announcement — different units, so rows are ranked by `uniqueUsers`, the one cross-type comparable number), `goalUsers` + `goalKind` (the type's success action, reconciling with get_content_analytics: flow/checklist completed, launcher activated, banner dismissed, resource-center clicked; null for tracker/announcement), `lastActivityAt`, `published`. Zero-activit…

Get a single end-user by their external id (the id you sent when identifying the user). Includes the user’s `companies` and `memberships` (the role they hold in each company) by default — override with `expand`. A single-environment token targets its env; with multiple, pass `environmentId`.

Read one locale of a content version as flat translation units: each has a stable `path`, the `source` text, the current `translation` ("" = untranslated), `kind` (`text` to translate; `destination` = a link / button / task navigation target and `media` = an image / embed URL — swap those per locale or leave empty to keep the source) and `outdated` (the source text changed AFTER this translation was saved: it still ships, but was written against older text — re-translate it). `stats` totals missing / outdated. Works on any version, including a published one; a locale never translated returns e…

List attribute definitions (the schema of custom attributes) for the project. Optionally filter by `name` (case-insensitive substring of EITHER the machine codeName or the human displayName — search by the codeName you see in conditions/identify), `scope` ("user", "company", "companyMembership", or "eventDefinition" for event attributes), or `eventName` (only the event-scoped attributes attached to that one event). `deleted: true` lists the soft-deleted ones instead. Returns `{ items, nextCursor }`.

List companies in an environment. A single-environment token targets its env; with multiple, pass `environmentId`. Filter by `segmentId` or a created-at range. Returns `{ items, nextCursor }`.

List Usertour content (flow, checklist, launcher, banner, tracker, resource-center, announcement) in the project. Filter by `name`, `type`, `published`, or a created-at range; `deleted: true` lists soft-deleted content instead (restorable via `restore_content`). Returns `{ items, nextCursor }`; pass `nextCursor` back as `cursor` to page.

List a content's versions (oldest first by default — pass `orderBy: -createdAt` for newest first). This list has NO live/published marker — to find which version is LIVE for users, read `get_content` and check `environments[].publishedVersionId` (publish is per-environment). Returns `{ items, nextCursor }`; pass `nextCursor` back as `cursor` to page.

List the project's environments — the environment ids that the env-scoped tools and `publish_content` accept. Each item carries `inTokenScope`: whether THIS credential may act on that environment — plan against it up front rather than discovering scope limits from write errors. **What an environment allowlist actually fences: DELIVERY and END-USER DATA** — publishing / unpublishing, users / companies / sessions / segment membership, analytics, the diagnose tools (per-user data), and the environment records themselves (an out-of-scope environment's SDK `token` is withheld as null). It does NOT …

List event definitions (the catalog of tracked events) for the project. Optionally filter by `name` (case-insensitive substring of either the machine codeName or the human displayName); `deleted: true` lists the soft-deleted ones instead. Returns `{ items, nextCursor }`; pass `nextCursor` back as `cursor` to page.

List the project's locales. The `isDefault` one is the SOURCE language content is authored in; every other `code` can carry a translation on each content version (`get_version_localization` / `update_version_localization`). Which translation a user receives is decided ONLY by their `locale_code` attribute matching a locale's `code` — the browser language is never detected. A default-only list means there is nothing to translate into yet: add a target language with `create_localization`. `deleted: true` lists the soft-deleted locales instead (the pool `restore_localization` draws from). Returns…

The permanent publish/unpublish ledger for one content, newest first — who put which version live in which environment, when, and who took it down. Each record: action (publish|unpublish), versionSequence (the v-number), environment, actor (dashboard user name, or API token name for API/MCP publishes), timestamp. Records outlive later deletion of the version, actor or environment (names then read null). Answers "when did this go live", "what was live in production last month", "who unpublished it". EPOCH: the ledger records events from the moment this feature shipped, forward; at rollout each …

Reverse lookup: everything still USING an attribute / event / segment / theme / content. Deleting an attribute, event, segment or theme is REFUSED while anything listed here uses it, so run this first to see what to rewire. (A content reference does not block deleting that content.) Scans the LIVE surfaces only: every live content's edited draft + published versions (start/hide rules, step triggers, question bindings, bodies, theme assignments), segment definitions, and theme variations. Matching is by exact stored reference, not text search. NOT covered: `{{ codeName }}` mentions inside text …

List the project's segments. Filter by `name` or `bizType` ("user" or "company"); `deleted: true` lists the soft-deleted segments instead. Returns `{ items, nextCursor }`.

List content sessions in an environment. Filter by `contentId`, `userId`, `completed`, or a created-at range. To RE-TEST a single-session surface (banner / launcher / resource center) for a user, find its session here and delete_session it — and never "clean up" with usertour.endAll() in the page: ending counts as the lifetime session, deleting is the reset. A single-environment token targets its env; with multiple, pass `environmentId`. Returns `{ items, nextCursor }`.

List the project's themes (id, name, isDefault, variationCount) — the theme ids accepted by a version's `themeId`. Optionally filter by `name`. Returns `{ items, nextCursor }` — page until `nextCursor` is null before concluding a theme does not exist. Check `variationCount` before switching content to another theme: variations do NOT travel with the content, so moving onto a theme with 0 variations silently drops conditional styling (dark mode …) for the users those conditions targeted. `deleted: true` lists the soft-deleted themes instead.

List end-users (the tracked business users your product onboards) in an environment. A single-environment token targets its env; with multiple, pass `environmentId`. Filter by `email`, `companyId`, `segmentId`, or a created-at range. Returns `{ items, nextCursor }`. Pass `expand` to inline each user’s companies / memberships (left out by default to keep the list lean).

List the outbound webhook endpoints configured for an environment. Signing secrets are not included — read one via the REST API or the dashboard.

Publish a version as an environment's live version (idempotent). Publishing is per-environment: if the token can act on a single environment it defaults to that one, but if it can act on multiple you must pass `environmentId` (it is NOT chosen for you). When the user has not named a target environment, never choose one yourself: ask, or leave the version unpublished and report that publishing needs an environment choice. Returns the content with refreshed `environments[]` and `editorUrl` (a dashboard deep link for human review) — after publishing, share that link so the user can see what went …

Remove a user from a company. DESTRUCTIVE, not a hide: the membership record and its membership-scoped attributes (e.g. a role) are deleted for good — re-adding the user creates a brand-new membership with empty attributes and a new join date, so remove-then-re-add is NOT an undo. With multiple environments you must pass `environmentId` (single-env projects default).

Remove a member from a manual segment. `memberId` is a user external id (user segment) or company external id (company segment) — per the segment bizType. With multiple environments you must pass `environmentId` (single-env projects default).

Bring a soft-deleted attribute definition back as it was (find it via `list_attribute_definitions` with `deleted: true`), so conditions that referenced it resolve again. Idempotent if it is not deleted. Returns the definition.

Restore a soft-deleted content (find it via `list_content` with `deleted: true`). It comes back as an UNPUBLISHED draft with its VERSIONS intact, and nothing is live again until you publish explicitly. `environments[]` comes back EMPTY — the per-environment publish state is not restored; what used to be live, where, reads from `list_publish_history`. Idempotent if the content is not deleted. Returns the restored content.

Restore a historical content version by forking it forward as the new editable DRAFT (config / data / theme / steps copied from it). This only STAGES a draft — despite the name it does NOT change what end-users see; the live/published version is untouched until you separately `publish_content` this restored draft. To recover a DELETED content, use `restore_content` instead. Returns the new version.

Bring a soft-deleted event definition back as it was (find it via `list_event_definitions` with `deleted: true`). Idempotent if it is not deleted. Returns the definition.

Bring a soft-deleted locale back exactly as it was (find it with `list_localizations` `deleted: true`). Every version translation it held returns with the enabled state it had, so enabled translations on published versions are delivered again at once.

Bring a soft-deleted segment back with its members (find it via `list_segments` with `deleted: true`). REFUSED (E1046) while its conditions use deleted attributes — the error names them with ids; `restore_attribute_definition` them first, then retry. Idempotent if the segment is not deleted. Returns the segment.

Bring a soft-deleted theme back as it was (find it via `list_themes` with `deleted: true`). It returns as a non-default theme. REFUSED (E1046) while its variation conditions use deleted attributes or segments — the error names them with ids; restore them first, then retry. Idempotent if the theme is not deleted. Returns the theme.

Clear an environment's live version for a content. The version itself STAYS frozen — having shipped once, it can never be edited again (edit by forking). `environments[]` empties here, but nothing is lost: every publish/unpublish lands in a permanent ledger — read it with `list_publish_history`. Per-environment: if the token can act on a single environment it defaults to that one, but with multiple you must pass `environmentId` (it is NOT chosen for you). Returns the content with refreshed `environments[]`.

Update an attribute definition. `codeName` and `scope` are IMMUTABLE — passing either is silently ignored (the call returns the unchanged value, no error). `dataType` CAN be changed, but only while nothing conflicts: with stored values that do not fit the new type the call fails with E1017 naming how many values block it, so a type change is safe to attempt — it either applies or tells you why not.

Update a content's metadata (name / buildUrl).

Write steps and/or start/hide rules to a draft (editable) content version. `steps` is the COMPLETE step list, not a patch — any existing step you omit is deleted. Omitting the `steps` FIELD entirely leaves all steps untouched (replacement applies only when the field is present), so a rules-only or theme-only update need not resend them. Match a step to update by its `cvid` (stable across forks) or primary `id`; omit both to add a new one. Editing a version that is live — or was EVER live (unpublishing does not unlock it; a shipped version is frozen as history) — fails with E0049; fork first wi…

Rename an environment.

Update an event definition (displayName / description; codeName is fixed).

Rename a locale or change its `locale` tag / `code`. **Changing `code` takes effect on LIVE content at once**: delivery picks a translation by matching `code` against each user's `locale_code` attribute, so users still carrying the old code fall back to the source language until their attribute matches the new one. A code held by another locale — including a soft-deleted one — is a conflict.

Update a segment's name, or replace a condition segment's conditions.

Update a theme's metadata (name / isDefault) and/or `settings` (a partial style patch, field-merged onto the current settings with auto colors derived). System themes (`isSystem: true` on list_themes) reject content changes (name / settings) — create_theme your own copy instead — but `isDefault: true` IS allowed on them: it only moves the project default pointer. `variations` writes REPLACE the whole list (see the field description).

Write translations for ONE locale of a content version, and/or switch its delivery on or off. `translations` maps a unit `path` (from `get_version_localization`, verbatim) to the translated text; only listed units change and a blank value keeps the existing translation. Unknown paths reject the whole write — re-read the units if the source changed. **Send every unit you are fixing for this locale in ONE call**: a save re-bases drift tracking for the whole translation on the current source, so `outdated` flags on units you left out are cleared too. A translation only reaches users when `enabled…

Update an outbound webhook endpoint (URL, topic subscriptions, enabled, description).

Create or update a company by external id (idempotent). Attributes merge into the existing ones. A value is a literal, null (remove), or ONE operation object: {set}, {set_once}, {add} (Number, negative to subtract), {union} / {remove} (List, deduplicated). Values are coerced losslessly to the definition type (42 into a String attribute becomes "42"); a value that does not fit is rejected. An attribute with NO definition yet is AUTO-CREATED with its type inferred from this first value — pin it with {set: value, data_type: "string" | "number" | "boolean" | "datetime" | "list"} when the value cou…

Create or update an end-user by external id (idempotent). Attributes merge into the existing ones. A value is a literal, null (remove), or ONE operation object: {set}, {set_once} (only when absent), {add} (Number, negative to subtract; starts at 0), {union} / {remove} (List, deduplicated). Values are coerced losslessly to the definition type (42 into a String attribute becomes "42", "42" into a Number becomes 42, any ISO 8601 date-time is normalised to UTC); a value that does not fit is rejected — a date-only string or an epoch number never fits DateTime. An attribute with NO definition yet is…

Dry-run usability check for a draft version — the same rules `publish_content` enforces, without changing anything. Returns `{ ok, errors, warnings }`; `errors` are what would block publish (e.g. a tooltip step with no target, an empty checklist, no theme). Run this after authoring and before `publish_content`.