pendo-ontology-mcp

A semantic ontology layer for Pendo, as an MCP server. Pairs with the Pendo MCP server: Pendo MCP is the data plane (live entities, usage, retention, funnels); this server is the meaning plane — the business concepts, definitions, entity relationships, causes, and playbooks your workspace has agreed on.

Why

LLM agents querying product analytics fail in a characteristic way: they don't know what your objects mean. Feature and segment names encode tribal knowledge, business terms like "activation" have workspace-specific definitions that live in people's heads, and the relationships between objects and business goals are written down nowhere — so agents ask endless follow-ups and produce confidently wrong answers.

This server is the place where that meaning gets written down — and it's designed so the LLM itself does most of the writing. The flywheel:

you ask questions → the model learns what you care about
  → it proposes/records concepts here (you review)
    → every future question is grounded in your definitions
      → answers get sharper → you ask more

The ontology store is a single portable JSON file: diffable, version-controllable, and an organizational asset that survives model swaps and agent rewrites.

What it is (and isn't)

• A typed JSON graph, not RDF/OWL. Its consumers are an LLM context window and a human reviewer.
• Query-language agnostic. Concepts carry a prose measurementHint ("weekly cohort retention over the measured features"), not query templates. The agent turns hints into concrete Pendo MCP calls (entityUsageTimeSeries, cohortRetentionCurve, …).
• No LLM calls inside the server. The client model is the intelligence; this server contributes deterministic guarantees (stable ids, phrase-match floors, coverage gaps) and durable storage.

Data model

STRUCTURAL (synced/pushed, rebuildable)        SEMANTIC (the asset)
─────────────────────────────────────          ─────────────────────────────
EntityNode                                     Concept
  id: "feature:<pendoId>"  ← stable              name, definition
  kind: feature|page|segment|                    measurementHint (prose)
        productArea|trackEvent|object            measures: [entity ids]
  pendoId  ← valid directly in Pendo tools       causes[]  (+ questionTemplate)
  name, appId?, url?, groupId?                   actions[] (+ questionTemplate)
                                                 tags[], source

Stable ids mean concept links survive full re-syncs. Entities deleted upstream leave dangling references that are ignored, never destroyed — a later sync may bring them back.

Install

git clone <this repo> && cd pendo-ontology-mcp
npm install && npm run build

Claude Code

claude mcp add pendo-ontology -- node /path/to/pendo-ontology-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "pendo-ontology": {
      "command": "node",
      "args": ["/path/to/pendo-ontology-mcp/dist/index.js"],
      "env": {
        "ONTOLOGY_STORE_PATH": "/path/to/team/ontology.json"
      }
    }
  }
}

Environment

Variable	Default	Purpose
ONTOLOGY_STORE_PATH	~/.pendo-ontology/ontology.json	Where the ontology lives. Point at a repo file to share with your team.
PENDO_INTEGRATION_KEY	—	Enables the optional sync_from_pendo direct REST sync. Not needed when pairing with Pendo MCP.
PENDO_API_BASE	https://app.pendo.io/api/v1	Override for EU/other regions.

Tools

Tool	Purpose
get_product_map	Overview: entity counts + every concept (definition, measurement hint, measured entities with pendoIds, causes, actions). Call first.
lookup_ontology	Search entities & concepts by name. Product areas expand into member features.
get_entity_catalogue	Full registered catalogue, features grouped by area — for picking measure links.
upsert_concept	Create/update a concept. autoLink: true adds deterministic phrase-matched entities.
delete_concept	Remove a concept (cause links to it are scrubbed).
suggest_links	Deterministic phrase-match candidates for a problem statement — the precision floor under the model's own semantic picks.
list_coverage_gaps	Entities no concept measures yet. Join with Pendo MCP usage data to rank concept candidates.
ingest_pendo_payload	The easy sync path: pass a RAW Pendo MCP tool result (listCountables, listProductAreas, segmentList, …) verbatim — array, wrapper object, or JSON string — and it's normalized and merged. Per-item evidence (elementPathRules → feature, url → page, kind-named wrapper keys) beats the kind hint.
register_entities	Structured push with explicit kinds (merge or replace). Use when you've already reshaped the data.
sync_from_pendo	Optional direct REST sync (needs PENDO_INTEGRATION_KEY).

Resource: ontology://digest — a markdown digest of the whole ontology, ready to be pulled into context.

The pairing workflow (with Pendo MCP)

1. Seed the structure — ask Claude:

   "List my product areas and features via Pendo, then register them in the ontology."

   Claude calls Pendo MCP (listProductAreas, listCountables, segmentList) and pipes each raw result straight into ingest_pendo_payload — no reshaping, no Pendo API key. (Alternatives: register_entities for pre-shaped data, or PENDO_INTEGRATION_KEY + sync_from_pendo for direct REST sync.)

2. Define what matters — ask:

   "Define a concept 'Activation': accounts that used ≥3 core features in week 1. Map the entities it measures."

   Claude drafts the concept, picks semantically-related entities from get_entity_catalogue (plus the suggest_links floor), and saves with upsert_concept.

3. Let usage drive coverage — ask:

   "What high-usage entities aren't covered by any concept?"

   Claude joins list_coverage_gaps with Pendo MCP usage (entityUsage) and proposes new concepts from the gaps.

4. Ask grounded questions — from now on:

   "How is Activation trending?"

   Claude reads the concept (definition + measurementHint + measure pendoIds) and goes straight to the right Pendo MCP calls — no follow-up questions, no guessed IDs, your definition every time.

Design notes

• Phrase-matching is the floor, not the ceiling. Single-token name matching measured 119 false positives for "agent" in a real workspace; two-word phrases stay precise but can't see semantics. The model does the semantic mapping; suggest_links/autoLink guarantee the obvious matches are never missed.
• Ontologies don't work on day 1. Meaning is distilled from use — questions asked, usage observed, definitions clarified. Start with structure + one or two concepts; let the flywheel run.
• Errors are results. Lookups return notes, not exceptions; a miss tells the model exactly which fallback to take.

License

MIT