| name | mixpanel-mcp |
| description | Use this skill for any Mixpanel question about Mosaic Wellness brands — MTU, funnels (PDP/cart/checkout/purchase), retention, cohorts, event property exploration, or lookups against the Mosaic event lexicon. Triggers on: Mixpanel, MTU, funnel, retention, cohort, brand analytics, lexicon, RNCL events, plus brand nicknames (mm, lj, bw, as, own, gf, affl, dochub, rwdy, rl). Use this when the question is about event-derived behavioral analytics; for live operational data (orders, CS tickets, deployments) use kai-mcp instead.
|
Mosaic × Mixpanel
The Mosaic Wellness Mixpanel org (2242951) has full Business Context
configured at the org level. The required-by-MCP Get-Business-Context
call carries the canonical brand → project resolver, prod-default rule,
geo expansions, and the lexicon pointer — don't duplicate that map
here, read it from Business Context at runtime.
This skill carries the bits Business Context doesn't: the lexicon query
script and the patterns for using it.
Setup
To get a Mixpanel Service Account token (the only credential this skill
needs), follow references/setup.md — Mosaic-specific click-by-click steps
for the Mosaic Wellness org. The tools-init skill automates the same
flow with live token validation.
Required call order
- Always call
Get-Business-Context (with organization_id=2242951
OR a known project_id) first in any new Mixpanel conversation.
- For brand-scoped queries, resolve
(brand, env=prod, geo=IN) →
project_id via the Business Context tables.
- For event names, use canonical
event_name from the lexicon — query
it via the script below, never paraphrase. Mixpanel is case-sensitive.
Lexicon (canonical event catalog)
The lexicon is a generated catalog of every active event across Little
Joys, Man Matters, and Absolute Sciences — 1197 events across 22 flows,
with per-event volume per brand and full property metadata. It lives
in the meta-repo, not in this plugin, because it's regenerated by
build_event_map.py whenever new brand exports drop in.
Canonical paths:
| File | Size | When to use |
|---|
Mosaic_events_mapped.json | 9.8 MB | Full — properties included. Source of truth. Do NOT Read directly — use the query script. |
Mosaic_events_index.json | 510 KB | Slim — no properties. Same data otherwise. |
Mosaic_events.html | 6.2 MB | For humans (double-click to open). |
All three live in mosaic-meta-repo/docs/resources/mixpanel/lexicon/.
Use the query script — never Read the JSON
The skill ships a script at:
${CLAUDE_SKILL_DIR}/scripts/lexicon-query.py
(${CLAUDE_SKILL_DIR} resolves to this skill's own folder — see the
official Claude Code skills docs at
https://code.claude.com/docs/en/skills.md.)
The script auto-locates the lexicon JSON via (in order):
$MOSAIC_LEXICON_JSON env var- Sibling
../mosaic-meta-repo/docs/resources/mixpanel/lexicon/Mosaic_events_mapped.json
~/Desktop/repositories/mosaic/mosaic-meta-repo/...- Broader sibling-directory search
If none resolve, it exits 2 with a clear message — tell the user to set
MOSAIC_LEXICON_JSON or pass --lexicon PATH.
Commands (all output JSON to stdout)
lexicon-query.py list-flows
lexicon-query.py list-events pdp --top 5 --brand little_joys
lexicon-query.py event "PDP Viewed"
lexicon-query.py event-properties "PDP Viewed" --brand man_matters
lexicon-query.py search "checkout" --flow checkout --brand man_matters
lexicon-query.py top 10 --brand man_matters
lexicon-query.py resolve-event "add to cart"
When to use which
| User asks… | Run |
|---|
| "What's the canonical event for X?" | resolve-event "X" first, pick highest-scoring candidate |
| "Show me the PDP funnel events for LJ" | list-events pdp --brand little_joys --top 10 |
| "What properties does Purchase Initiated have?" | event-properties "Purchase Initiated" --brand <brand> |
| "Top events firing on MM right now" | top 20 --brand man_matters |
| "Find every event that mentions referral" | search "referral" |
| "What flows does the lexicon track?" | list-flows |
After the script returns canonical event names, pass them to Mixpanel MCP
tools (Run-Query, Get-Events, List-Properties) — those need exact
event names with correct casing.
Brand key mismatch (3 codes, same brand)
Three brand-encoding conventions exist; they don't auto-convert:
| Brand | Lexicon key | Mixpanel BC nickname | Kai brand code |
|---|
| Little Joys | little_joys | lj | LJ |
| Man Matters | man_matters | mm | MM |
| Absolute Sciences | absolute_sciences | as | AS-IN |
| Bodywise | (not in lexicon yet) | bw | BW |
| ...other brands | (not in lexicon yet) | various | (some only) |
When passing --brand to the script, use the lexicon key (snake_case
with underscores).
Lexicon flows (actual 22)
acquisition · auth · onboarding · navigation · browse-home ·
browse-shop · search · pdp · cart · checkout · purchase ·
post-purchase · habits · referral · rewards · content · consultation ·
engagement · ui-interaction · telemetry · error · uncategorized
uncategorized is the catch-all for events whose flow couldn't be
inferred — 318 events, mostly low-volume. Treat it as noise unless the
user explicitly asks about a specific uncategorized event.
Multi-brand queries
When the user asks for a metric "across all brands":
- Run the query against each brand's prod project separately (resolved
via Business Context).
- Do not assume schema consistency — event names and properties
drift between brands. Validate with
lexicon-query.py event-properties <name> --brand <brand> before running a cross-brand funnel.
- Aggregate results client-side. Mixpanel does not support cross-project
queries natively.
Project IDs not in Business Context (edge cases)
Two utility/sub-projects exist that the Business Context intentionally
omits because they're not first-class brand surfaces:
- DocHub - Test
2829032 — DocHub QA project; never default to this.
- E-Commerce
3018488 — empty workspaces, treat as deprecated.
Common asks → recipes
| Ask | Recipe |
|---|
| "MTU for Man Matters this month" | Get-Business-Context → project 2764907 → lexicon-query.py top 3 --brand man_matters --flow telemetry to find the canonical activity event → Run-Query distinct users, period = current month |
| "PDP → AddToCart → Purchase funnel for Little Joys" | lexicon-query.py resolve-event "PDP viewed", then resolve-event "add to cart", then resolve-event "purchase" to pin canonical names → Run-Query funnel on project 2707205 with those exact names |
| "What properties can I filter PDP Viewed by?" | lexicon-query.py event-properties "PDP Viewed" --brand <brand> |
| "Affluence referral conversion" | Affluence is a single project 3537036 — NOT in the lexicon. Discover events via List-Properties on the project directly, or Get-Events |
Gotchas
uncategorized is mostly noise — 318 events, low signal. Skip
unless the user asks for a specific event there.- Lexicon only covers MM, LJ, AS today. For Bodywise, OWN, Get Fitter,
DocHub, Affluence, Rwdy, Root Labs —
event_in_lexicon = false. Use
Mixpanel List-Properties / Get-Events against each project directly
to discover schema, since brand schemas drift.
- RNCL suffix on event names (e.g.
"App Launched (RNCL)") means the
event fires only on the React Native mobile apps, not on web. Web
events typically lack the suffix.
- Bodywise vs Bodywise Health — two separate Mixpanel projects.
Confirm with the user which surface before defaulting.
- DocHub events are doctor-facing, not consumer.
- The lexicon JSON is regenerated by
mosaic-meta-repo/docs/resources/mixpanel/lexicon/build_event_map.py.
Drift is possible — when in doubt, re-run the generator. The script
will reflect updates on the next call because it reads the file fresh.
- The script returns JSON only. Pipe to
jq or parse with python
if you need to transform; don't try to grep the output text.
