Gentic Loyalty — Documentation

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Loyalty, you need an API key to authenticate your requests.

1. Go to gentic.co/loyalty and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/loyalty. For Claude Code:

claude mcp add gentic-loyalty \
  --transport http \
  https://mcp.gentic.co/loyalty \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Loyalty agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/loyalty/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/loyalty/gentic-loyalty.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

• User wants to analyze their loyalty program — points earned, redeemed, or outstanding.
• User wants to know how VIP tiers differ in repurchase rate, order value, or retention.
• User wants to measure referral performance — how many, and what revenue they drove.
• User wants to understand reward economics: what a reward costs versus what it returns.
• User wants to sync their Rivo loyalty data into their Brain for analysis.
• User wants to join loyalty data against subscriptions, orders, or survey responses.

5. Workflow

1. 1. Connect Rivo once, then sync without credentials

   The Loyalty server sources the Rivo connection (the REST API key) from the org's connected integration (Gentic dashboard → Integrations → Rivo). You never pass credentials to the tools — connect once in the dashboard and the server reads the encrypted connection automatically. Call `rivo_connection_status` first (it's free) to confirm the org is connected; if it returns `{ connected: false }`, point the user to Integrations → Rivo. It never returns the API key. Pass `check_live` when you want it to actually probe Rivo rather than just report that a key is stored.

2. 2. Sync loyalty data into the Brain with `rivo_sync`

   `rivo_sync` is **free**. It is READ-ONLY and warehouses five resources into per-org tables — `rivo_points_events`, `rivo_points_redemptions`, `rivo_rewards`, `rivo_referrals`, `rivo_vip_tiers` — dedupe-upserted on their natural key, so a re-sync refreshes existing rows in place rather than duplicating them. Returns `{ synced: { <resource>: count }, has_more, next_cursor, persisted, pages_fetched, stalled }`.

3. 3. Walk the data with bounded, resumable pagination

   Each `rivo_sync` call is BOUNDED: it pages the requested resources only until `max_pages_per_run` pages OR `max_seconds_per_run` seconds are reached, then returns `has_more` and a `next_cursor: { resource, since_id }`. To finish a large backfill, call again passing that `next_cursor` back as `cursor` until `has_more` is false — the walk resumes exactly where it stopped, and because it's an id cursor rather than a page offset, rows inserted mid-walk can't shift the window under you. Use `resources` to sync only the tables you need. Check `stalled` before you trust a walk as complete: a non-empty `stalled` means a resource stopped because its cursor could not advance, not because it ran out of rows — that needs a look rather than another call.

4. 4. Count and aggregate with `query_data`

   The loyalty tools warehouse data; they don't analyze it. For points issued versus redeemed, redemption rate by reward, referral counts and revenue, or tier distribution, use `query_data` (Gentic Data MCP) over the `rivo_*` tables — standard SQL GROUP BY / COUNT / SUM over the synced rows. Sync first (or re-sync incrementally) so the numbers are current.

5. 5. Join loyalty against the rest of the business — this is the point

   A loyalty dashboard can tell you redemption counts. It cannot tell you whether the program works, because the answer lives in tables it has never seen. Since everything lands in the same per-org Brain, join `rivo_*` against what you've synced elsewhere: VIP tier against subscription retention (`skio_*` / `loop_*`) for LTV by tier, points redemptions against order history for whether earning actually drives repurchase, referrals against your ad-attributed revenue to see what you were already paying for, and tier or redemption behaviour against survey responses (`fairing_*`) for why. Compose it across tables with `query_data`.

6. 6. Present results clearly

   Don't dump raw JSON. Summarize the numbers — points issued and redeemed, top rewards, referral counts and revenue, tier distribution — and cite the counts. After a sync, report three things, not two: how many rows were `persisted` per resource, whether `has_more` is true (there's more to page through), and whether anything `stalled`. The third is the one that changes what you say. A stalled resource means the walk is INCOMPLETE even when `has_more` is false, so a summary of persisted counts alone would read as a finished sync when it isn't — name the stalled resources and say the data is partial rather than presenting the run as successful. For recurring checks, re-run `rivo_sync` to refresh the tables before querying.

6. Tool Reference

2 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

8. Notes

• Organization-scoped: the Rivo connection comes from the org's connected integration (dashboard → Integrations → Rivo). No credential is ever passed to the tools.
• Cost: both `rivo_connection_status` and `rivo_sync` are **free**. You pay only for analytics you run over the synced data (e.g. `query_data`). Pricing is pulled live from the Gentic MCP manifest.
• `rivo_sync` is READ-ONLY. It warehouses your loyalty data and never writes back to Rivo — it cannot grant points, issue rewards, or change a customer's tier. That boundary is deliberate: a connector that can award value is a different product with a different risk profile.
• Rows are deduped on their natural key: re-syncing refreshes the same row (mutable fields and all) rather than duplicating it.
• Syncs are bounded and resumable: each call stops at `max_pages_per_run` / `max_seconds_per_run` and returns `next_cursor: { resource, since_id }`; pass it back as `cursor` to continue until `has_more` is false. A non-empty `stalled` in the result means a resource stopped because its cursor could not advance — that is not a finished walk, and calling again will not fix it.
• The five tables — `rivo_points_events`, `rivo_points_redemptions`, `rivo_rewards`, `rivo_referrals`, `rivo_vip_tiers` — are queried with `query_data` for all counts and aggregations.
• A Rivo API key is scoped to a single store, so which store the data belongs to is captured automatically when you connect and there is nothing to select per call.