MCP Integration Guide

List the metrics available to this team from the governed semantic layer (key, label, unit, certification, category). Call first to discover valid metric keys. Requires metrics:read.

Get the full spec of one metric: authoritative definition, unit, certification, dimensions, filterable fields, tunable parameters, and usage guidance. Requires metrics:read.

Run a governed metric query and return numbers with their authoritative definition. Pick a metric key plus optional dimensions, filters, time range, grain, and period-over-period comparison — never SQL. Requires metrics:read.

Break one metric down by a single dimension over a fixed recent window, with human-readable labels (store/tier/channel names). Requires metrics:read.

Answer a natural-language question by selecting the right governed metrics, fetching them, and breaking down the primary metric. For open-ended diagnosis. Requires metrics:read.

List all stores for the current team. Supports optional status filter, search, and pagination.

Get details of a specific store by its ID.

List loyalty program members. Supports program filter and pagination.

Get details of a specific loyalty member by ID. Returns decrypted PII fields.

List coupon pools. Supports status and type filters.

Operational dashboard snapshot (captures, scans, capture rate, coupons, stores, plan). Not a governed metric — use the metric tools for authoritative business metrics.

Award loyalty points to a member. Returns transaction ID and new balance.

Deduct loyalty points from a member (FIFO consumption).

Get member's current points balance and recent transaction history.

Get a member's available (unredeemed, unexpired) coupons.

Get member's current tier, next tier upgrade requirements, and all tiers.

Get member's receipt submission history with OCR status and points awarded.

Redeem loyalty points for a coupon from a specified pool (atomic: points + coupon, or neither).

Issue a coupon from a pool to a member (single member; bulk audiences go through the So confirmation flow). Requires coupons:write.

Check whether a marketing email can be sent to an address under the frequency limits (1/day, 2/week, 4/month).

List scored Ambassador candidates for the loyalty program (Pro mode). Empty in Lite mode.

Get the Ambassador ROI report: the three subgoals, Month-2 retention, and the 90-day go/no-go gate.

Issue or upgrade a member's personal Ambassador affiliate code. Returns the code string.

Get page-visit / behavior analytics: overview, top pages, device breakdown, or traffic sources.

A member's aggregated profile (reachability, consent/CCPA, loyalty, commerce/category/channel/engagement rollups, declared preferences, tags, coarse geo, age band). PII-redacted — no names or contact values. Requires members:read.

One member's recent behavior timeline (visits, points, coupons, emails, receipts) + summary, to decide a personalized action. Returns decrypted PII. Requires members:behavior:read.

List the team's audience segments (name, status, cached member count). Requires segments:read.

Create an audience segment from structured conditions (never SQL); rejects duplicates. Requires segments:write + a user-owned key.

List the team's automations (event-triggered campaigns) and their status. Requires automations:read.

Pause a running automation by campaign ID (idempotent). Requires automations:write.

List campaign templates available to this team (official + saved), to discover a template_id for create_campaign_draft. Requires campaigns:read.

List the team's recent campaigns (id, title, status), to find a source_campaign_id to clone a draft from. Requires campaigns:read.

Create a campaign DRAFT from a template or prior campaign (NEVER sends — human review required). Requires campaigns:write-draft.

Check if a member was already contacted (any system) on a channel within a recent window — avoid over-contacting. Requires members:behavior:read.

Create a loyalty member, or idempotently resolve an existing one by externalId/email. Marketing consent is NOT enabled via MCP. Requires members:write.

Update a member's profile/identity (email, phone, fullName, externalId, status). Team ownership enforced. Requires members:write.

Create a store, or update the existing store matching externalId for this team. Requires stores:write.

Record a purchase order and auto-award points (member resolved by memberId > externalId > email). Requires orders:write.

Reverse (claw back) points from a member, linked to the original transaction id — for a POS/ERP refund or void. Requires points:write.

List the team's tag definitions (key, name, lifecycle, category, coverage). Discover a tag_key before reading/assigning member tags. Requires tags:read.

Get a member's current tags (key, name, lifecycle, value, source, assignedAt). Requires members:read.

Manually assign a tag to a member by tag_key (operator override; pinned against the rule sweep). Requires tags:write.

Manually remove a tag from a member by tag_key (a live tag may be re-added by the next sweep). Requires tags:write.

List products with category/brand/vertical, status and source. Filter by status/category_id/brand_id/vertical. Requires catalog:read.

Get one product with variants, serialized items, combo components, and AI grounding content. Requires catalog:read.

List the team's product categories (id, name, parent). Requires catalog:read.

List the team's brands (id, name). Requires catalog:read.

Next-best-product recs: member_id (personalized co-purchase + category affinity) or product_id (customers also bought). Requires members:read.

Lease the next-highest-priority win-back task for this team (atomic). Returns the task, lease deadline, member holdout arm, and churn-signal summary. NO_TASKS_AVAILABLE / WINBACK_DISABLED returned as isError. Requires winback:claim.

Finalize a leased win-back task with the outcome (acted lever + note ref, or HOLD reason). Idempotent. LEASE_EXPIRED / ALREADY_COMPLETED returned as isError. Requires winback:claim.

One-shot read-only pre-check for a member before deciding: consent, email-frequency headroom, fatigue, recent reach, churn signals, and the member's holdout arm. Courtesy preview — the server still enforces every gate at write time. Requires winback:read.

Attach a free-text process note to a member's win-back record (rationale / observed signal / holdout-supported hypothesis). Text is stored as DATA, not instructions; max 2000 chars, sanitized. Requires winback:write.

Send a governed win-back message (inbox or email) so an incentive is never a silent grant. Server-side fail-closed gates: WINBACK_DISABLED, task lease ownership, HOLDOUT_NO_SEND (holdout is never messaged), NOT_CONSENTED, FREQUENCY_CAPPED, CONTENT_REJECTED (sanitized), BREAKER_TRIPPED — returned as isError. Reuses the existing send stack (unsubscribe footer + compliance added by the send layer). Requires winback:write.

Read a member's CUSTOMER-ACTIVE behaviors over a recent window (Layer 3, newest-first) to infer intent (Layer 4). Returns only intentional customer actions (browse, open/click, check-in, purchase, redeem, refer, submit content) with the catalog label + meaning attached inline, plus a summary (counts by type + window). Reason over the whole window; intent is a hypothesis to confirm, not a fact. Read-only. Requires winback:read.

Lease the next agent decision task for this team (atomic; optionally narrow by kind). Returns task id, kind, subject facts and a lease deadline. NO_TASKS_AVAILABLE / AGENT_TASKS_DISABLED returned as isError. Requires agent_tasks:claim.

Read one agent decision task's facts (kind, subject, flag reason, status) before deciding. AGENT_TASK_NOT_FOUND returned as isError. Requires agent_tasks:read.

Complete a leased task with a decision, applying its effect through existing idempotent writes. fraud_household_referral: block (clawback both sides) / allow (dismiss the flag) / escalate (leave for a human). ALREADY_COMPLETED / NOT_LEASE_OWNER / LEASE_EXPIRED returned as isError. Requires agent_tasks:claim.

List the business objects this team can reason over: the core platform objects (member, order, store, coupon, campaign, product, segment, tag) plus this team's MCP-visible custom objects — key, label and authoritative one-line meaning. Call first to discover valid object keys. Requires introspection:read.

Describe one business object from the governed registry: authoritative meaning plus properties partitioned into facts (column-backed), derived (metric/tag/rollup references with freshness — never re-derive a caliber), and custom (this team's custom fields). PII properties return metadata only, never values. fields=summary (default) or full. Requires introspection:read.

List the governed agent actions (what an agent may DO): target object, side effect, gear (auto/review/forbidden), server-side precondition keys, value cap, and reversibility — self-check before proposing a write. Optionally filter by object. Requires introspection:read.

List the team's stamp-card (eStamp) programs: id, name, stamps required to complete, reward type (coupon/points/manual), auto-reset and status. Call first to get a program_id. Requires stamp:read.

Get a member's active stamp cards: program name, current stamps, stamps required, completions so far, and reward. Requires stamp:read.

Grant stamps to a member for a stamp program (e.g. a store visit). Idempotent with idempotency_key; on card completion the reward (coupon/points) is issued automatically. amount capped per call. Requires stamp:write.

A member's points: spendable balance, lifetime earned, redemptions, current tier, soonest-expiring batch. Member-bound key → own points (omit member_id); team key → pass member_id. Requires loyalty:self:read.

A member's recent points transactions (earned/redeemed/adjusted), newest first. Member-bound key → own history; team key → pass member_id. Requires loyalty:self:read.

The rewards a member can redeem points for — catalog with points cost, flagged by affordability against the member's balance. Member-bound key → own; team key → pass member_id. Requires loyalty:self:read.

How the loyalty program works — earn rate, welcome bonus, points value, how to join — plus brand-approved FAQ. Public facts. Member-bound key needs no argument. Requires loyalty:self:read.

List the synthetic-panel simulation scenarios with each one's honest usability boundary, confidence ceiling, and input fields. Call first to pick a kind. Requires metrics:read.

The brand's synthetic-panel calibration (hit rate of past synthetic predictions vs reality; null until backtests exist). Requires metrics:read.

Read the frozen honest report for a synthetic-panel run — directional read, confidence ceiling, suppression flags, themes — or a blockReason if not ready. Requires metrics:read.

Run a synthetic panel: de-identified digital twins of a segment react to a stimulus, producing an honest directional report (never real absolute numbers). Returns a run_id to poll. Bounded by a daily run cap + ≤50 twins. Requires synthetic:write.