| name | epiphan-ai-mcp-guide |
| description | Reference for Epiphan AI MCP tools — CRM, sales intel, device analytics, lead qualification, marketing (Semrush/GA4/GAds). |
Epiphan AI — MCP Tools Guide
Day-one reference for the Epiphan AI MCP toolset — which tool answers which question across CRM sales
data, device analytics, HubSpot CRM (read + admin-scoped writes), Clari call recordings, contact
enrichment, lead qualification, curated analytics datasets, and marketing intel (Semrush/GA4/GAds).
Use it to pick the right tool fast, know its defaults and caveats, and avoid the wrong namespace.
<quick_start>
- Start with
ask_agent — natural language handles most questions (revenue, calls, products, pricing).
- Direct lookups → the "All Available Tools" table below (e.g.
sales_brief for a customer, weekly_brief for the tracker, qualify_lead for inbound, query_dataset for repeatable numbers).
- Namespace: default to
Epiphan Ai, not the Epiphan CRM subset (see Namespaces section).
- Deeper reference in this skill's folders:
resources/ — per-domain tool guides: crm-tools.md, sales-tools.md, enrichment-tools.md, product-tools.md, marketing-tools.mdreference/ — tool-examples.md (worked examples) and verticals.md (5-vertical persona pack)
- Customer-facing assets → defer to the
epiphan-brand-assets skill (separate Epiphan Brand MCP).
</quick_start>
Epiphan AI gives you access to CRM sales data, device analytics, HubSpot CRM, call recordings, contact enrichment, lead qualification, and marketing analytics — all through natural language.
What You Can Do
Sales & Revenue
Ask anything about sales data. Revenue, customers, products, trends — from 2010 to today. All currencies auto-converted to USD.
"Top 10 customers by revenue in 2025"
"Monthly sales trend for Pearl Mini last 2 years"
"Compare Q1 vs Q2 by region"
"Which products have declining sales?"
"Pearl Nano vs Pearl Mini revenue comparison"
"New customers acquired in 2025"
"Customers who haven't ordered in 6 months"
"Average order value by customer segment"
"80/20 analysis — who are the customers driving 80% of revenue?"
Customer Deep Dive
Get a complete picture of any customer in one shot. Just say the name — fuzzy matching handles misspellings.
"Sales brief for B&H Photo"
"Tell me everything about Stanford University"
"Customer brief for University of Toronto"
Returns: company info, 12-month revenue, top products, open deals, key contacts, recent notes.
Look up specific orders or history:
"Show B&H Photo order history"
"Find order PO-2024-1234"
"All orders for customer ID 5678 in 2024"
Call Prep & Handoffs
Before a call — get fully prepared:
"Sales brief for MIT"
"Search Clari for calls with mit.edu in the last 90 days"
"Show engagement timeline for MIT — last 6 months"
"What's the deal pipeline for MIT?"
After a call — hand off to AE:
"Create AE handoff for MIT, contact: john.smith@mit.edu"
Generates: bottom line summary, pre-call tasks for AE, aggregated intel from CRM + devices + Clari calls + HubSpot engagement. Optionally creates a HubSpot note.
Optional ebStrategy block — when provided, it's appended to the handoff note as an "Economic Buyer Strategy" section AND written to the deal's eb_intel custom properties:
ebTitleHypothesis — hypothesized EB title (e.g. "VP Academic Affairs")ebPriorityHypothesis — which EB priority the pain maps tochampionActivationStatus — exploring | activated | pursuingdoubleUpfrontSeeded — booleanknownEvalSteps — string array (e.g. IT security review, faculty pilot)
Omit ebStrategy and the handoff is unchanged (backward-compatible). HubSpot writes are admin-scoped.
BDR Call Activity & Coaching
"How many calls did Tim make today?"
"Dials to connect ratio for the BDR team this week"
"Total talk time by rep this month"
"Who did rhaynes call yesterday?"
"Any booked demos from calls this week?"
"Rep leaderboard for the last 30 days"
Clari call intelligence:
"Summarize Clari calls about Nexus products"
"Get summary for call ID 12345"
"Search Clari for calls with competitor mentions"
Task Briefs (Sales Rep Accountability)
See overdue + upcoming HubSpot tasks per rep. Highlights "follow up on sales related support ticket" tasks (auto-created from CS_Tickets pipeline) — most commonly missed.
"Task brief for Tim"
"Show overdue tasks for Lex Evans"
"Team task brief"
Returns: overdue / due-today / upcoming with deal context.
AE Drift Detection
Find contacts and deals that drifted away from a rep. Useful for handoff tracking and pipeline hygiene — surfaces records currently owned by other AEs where the target rep had recent engagement.
"What drifted away from Phillip in the last 7 days?"
"AE drift check for Lex"
days lookback: min 1, max 30, default 7.
Lead Qualification
Qualify inbound leads automatically. Detects junk, classifies against ICP, routes to region, drafts outreach email.
"Qualify lead 12345"
"Is contact 67890 a good lead?"
"Classify and write email for HubSpot contact 11111"
Returns: category (ideal_mql / warm_lead / nurture / junk), confidence score, region (NA/EMEA/APAC), power_level (atl / btl / unknown — above/below the line buyer authority), suggested email draft.
writeToHubSpot defaults to false — qualify_lead is a dry run unless you pass writeToHubSpot: true, which then updates the lifecycle stage + creates a qualification note. Writing is admin-scoped (Tim / Victor).
powerLevelOverride (atl | btl | unknown) — override the title-based ATL/BTL classifier when you know the contact's real authority. Sticky on the contact: later classifier runs won't downgrade it.
Contact Enrichment
Find phone numbers and emails for prospects.
"Find contact info for John Smith at Stanford"
"Enrich contact: Sarah Johnson at Microsoft"
"Look up email for this person"
3-tier lookup: cached data (instant) → HubSpot DB (instant) → Clay API (30-90s for new contacts). Provide LinkedIn URL for best accuracy.
Company Identification
Match spoken or misspelled company names. Great after sales calls when you're not sure about the spelling.
"Who is be an age photo?" → finds B&H Photo
"Identify company: samsun" → finds Samsung
"Match this company: standford univeristy"
Returns best matches from CRM + HubSpot with confidence scores.
Device Analytics (Pearl Fleet)
Pearl device registrations, usage, and fleet analysis. Data synced daily from production.
"How many Pearl devices does MIT have?"
"Find all devices registered by john@mit.edu"
"Devices registered in Germany with high idle rate"
"Show idle devices over 90 days for education vertical"
"Universities with most device registrations"
"Registration trends by country last 12 months"
"Devices active per day — last 30 days"
"Most active Pearl devices by usage"
Cross-data (devices + revenue):
"Customers with registered devices but no orders in 2024"
"Correlation between device count and order value"
"Which accounts have devices but no open deal?"
HubSpot CRM
Contacts, companies, deals — search and lookup.
"Search HubSpot for contacts at stanford.edu"
"Find deals with 'Nexus' in the name"
"Show open deals for company ID 12345"
"HubSpot company details for domain mit.edu"
"What's the pipeline summary?"
"Stalled deals over 30 days"
Competitive & Market Intel (Marketing Tools)
Semrush SEO:
"Semrush domain overview for vaddio.com"
"Compare organic keywords: epiphan.com vs crestron.com"
"What questions do people ask about lecture capture?"
"Who are epiphan.com's organic search competitors?"
"Backlinks to epiphan.com — top referring domains"
"Keyword difficulty for 'lecture capture software'"
Google Analytics:
"Top landing pages this month by sessions"
"Conversion rate by traffic source last 30 days"
"Compare organic vs paid traffic trends"
Google Ads:
"Campaign performance last 30 days"
"Ad creatives for the Pearl campaign"
"Which ads have the best conversion rate?"
Product Knowledge
Ask about Epiphan products — pricing, specs, features, comparisons, troubleshooting.
"What's the price of Pearl Mini?"
"How much does Epiphan Edge cost for 10 devices?"
"Does Pearl-2 support 4K? Is there an extra cost?"
"How do I set up Pearl Mini with Panopto?"
"What's the difference between Pearl Nexus and Pearl Mini?"
"Which encoder is best for NDI workflows?"
Uses structured product catalog (instant) + RAG from tech support docs for deep technical questions. Live CRM prices for pricing queries.
Clari Call Search (by Name)
Find calls by company name, contact name, or topic — not just by email.
"How did the Tufts University call go with Jesse Anderson?"
"Find calls about Old Dominion"
"What was discussed on the Stanford call last week?"
"Summarize Lex Evans' calls this month"
Searches the clari_calls table in PostgreSQL (7K+ calls with AI summaries, action items, competitor mentions).
Stripe Cloud Usage
Epiphan Cloud (Connect/Unify) usage tracking and renewal alerts.
"Which customers are approaching their usage contract limits?"
"Show Stripe usage for PLI"
"Cloud usage growth signals — who's increasing?"
"Churn risk: customers with declining usage"
Curated Analytics Datasets (Weekly Tracker / Repeating Reports)
Parameterized analytics with deterministic SQL — built for recurring reports (Cowork weekly sales tracker, BDR digests). Bypass ask_agent when you need consistent numbers.
5 datasets, common filters + group_by:
| Dataset | What | Example |
|---|
revenue | CRM orders, USD-converted, order_type_id < 30 | "Booked revenue MTD/QTD/YTD" |
deals_closed | HubSpot won/lost in date range | "Won deals last week, by outcome" |
pipeline_open | HubSpot active pipeline (excludes closed) | "Open pipeline by AE × stage" |
contacts_created | New HubSpot contacts with lifecycle/source | "New leads by lifecycle this week" |
rep_activity | BDR/AE engagements (emails, calls, tasks, meetings, notes) | "Tim + Ron activity last 7 days" |
"Use query_dataset: revenue from 2025-11-01 to 2026-04-29 by month"
"Open pipeline matrix — AE × stage for default sales pipeline"
"Won/lost deals last week, split by outcome"
"New contacts last week broken down by lifecycle and source"
"BDR activity for owner_ids 87486452, 423155215 last 7 days"
group_by supports cross-product matrix (e.g. ["owner","stage"]), period grain (period_day / period_week / period_month / period_quarter / period_year), and dimensional breakdown (owner / stage / outcome / country / lifecycle / source / pipeline). format=csv returns an embedded CSV file (Claude Desktop attaches it). Custom HubSpot lifecycle stage IDs are normalized to MQL/SAL/SQL/Customer/Junk/Declined/Nurture labels.
Raw SQL Export
Escape hatch when curated datasets aren't enough. export_query_csv runs a read-only SQL SELECT and returns the result as a CSV file (embedded resource).
"Export this query as CSV: SELECT ... FROM crm_orders WHERE ..."
Same SQL safety as execute_sql (SELECT/WITH only, no writes). Hard cap 50 000 rows.
Data Visualization
Generate Economist-style charts from any data.
"Create a bar chart of top 10 customers by revenue"
"Line chart: monthly revenue trend 2023-2025"
"Pie chart of revenue by region"
Always provide the data (JSON/table) alongside the request.
All Available Tools
| Tool | What it does |
|---|
ask_agent | Ask any CRM/analytics question in natural language |
sales_brief | Complete customer briefing in one call |
ae_handoff | BDR→AE handoff package with HubSpot note |
qualify_lead | Lead qualification: junk detection, ICP scoring, email draft |
identify_company | Fuzzy match company names across CRM + HubSpot |
enrich_contact | Find phone + email via Clay |
activity_get_timeline | Engagement history (calls, emails, notes, meetings) |
clari_search_calls | Search recorded sales calls |
clari_get_call | Full call details + optional transcript |
clari_get_call_summary | Quick call summary + action items |
hubspot_search_companies | Find HubSpot companies |
hubspot_get_company | Company details by ID |
hubspot_search_contacts | Find HubSpot contacts |
hubspot_get_contact | Contact details by ID |
hubspot_find_contacts_by_role | Role discovery — "who is the AV/IT Director at northeastern.edu". Keyed on email domain (ignores dirty company names). Params: domain, titles[] (optional; defaults to higher-ed AV/IT preset), limit. Unions HubSpot + Clay-enriched contacts, decision-makers first. Read-only. Use this for list-building instead of enrich_contact (which needs a known name) |
hubspot_search_deals | Find HubSpot deals |
hubspot_get_deal | Deal details by ID |
crm_get_customer | Legacy CRM customer by ID |
crm_search_customers | Search legacy CRM customers |
crm_get_order | Order details (fuzzy search) |
crm_get_customer_orders | Customer order history |
analytics_get_device | Pearl device lookup by serial |
analytics_search_by_email | All devices by registrant email |
search_product_catalog | Product pricing, specs, features, competitors (catalog + CRM prices + RAG) |
search_product_knowledge | Deep tech support RAG (troubleshooting, setup, firmware) |
task_brief | Overdue + upcoming HubSpot tasks per rep (or team) |
ae_drift_detect | Contacts/deals reassigned away from a rep (last N days) |
query_dataset | Curated parameterized analytics: revenue, deals_closed, pipeline_open, contacts_created, rep_activity |
weekly_brief | One-shot weekly sales tracker — bundles 9 query_dataset calls. Params: week_ending, ae_names, bdr_owner_ids, fiscal_year_start, target_annual_revenue, pipelines. Defaults: FY2026, Tim+Ron, $19.5M target |
export_query_csv | Raw read-only SQL → CSV file (escape hatch when curated datasets aren't enough) |
generate_image | Data charts and infographics |
get_upcoming_meetings | Calendar check |
HubSpot Write Tools (admin-scoped: Tim / Victor)
These mutate HubSpot. Restricted to an allowlist — others get a 403. Rate-limited: 1,000 writes / 5 min per user (bulk-friendly), 4 / 5 min per record.
| Tool | What it does |
|---|
hubspot_create_contact | Create contact. Idempotent — dedupes by email (returns existing on match). Entry stages only (lead/MQL/SQL/Cold Lead/SAL); accepts associateCompanyId |
hubspot_create_company | Create company. Dedup is domain-first: any existing company on the same registrable domain (eTLD+1 — www.carleton.ca, cunet.carleton.ca and carleton.ca all match) is flagged as the same institution (needsReview:true, matchType:"domain"), since that's the reliable key for dirty higher-ed names. Falls back to fuzzy company-name match on other domains. Reuse a candidate's companyId, or pass confirmDespiteSimilar:true to force-create a genuinely distinct org |
hubspot_create_deal | Create deal. No dedup — pass pipelineId + dealstage (from hubspot_deal_stages) |
hubspot_update_contact | Update fields on an existing contact (e.g. add a missing phone). Identify by contactId or email. Patches only the fields you pass: phone, mobilephone, jobtitle, firstName, lastName, company, website. Owner → use hubspot_update_contact_owner; lifecycle → hubspot_set_lifecycle_stage |
hubspot_update_company | Update fields on an existing company. Identify by companyId or domain (ambiguous domain → returns candidates, pass companyId). Patches only passed fields: name, city, country, state, industry, phone, website |
hubspot_update_contact_owner | Set contact owner. Validates ownerId against hubspot_owners |
hubspot_set_lifecycle_stage | Set lifecycle stage. Accepts ID, label, or alias (SAL/MQL/Cold Lead) — resolved + validated |
hubspot_create_contact_note | Create note on a contact (optionally on deal/company). HTML body, script tags stripped |
hubspot_create_contact_task | Create task on a contact. ISO 8601 due date, validated ownerId. taskType: CALL / EMAIL / TODO (default TODO) — pass CALL for dial/follow-up-call tasks (Nooks call lists) so they land as real Call tasks. No HubSpot connector needed |
hubspot_update_contact_note | Edit an existing note's body by noteId. HTML, script tags stripped + spacing normalized. Guardrail: only notes our integration created, or ones newer than ~7 days, can be edited — older human-authored notes are protected (Forbidden). HubSpot keeps per-property history as a backstop |
hubspot_update_contact_task | Edit an existing task by taskId. Any subset of subject / body / dueDate / status / ownerId / taskType / priority; omitted fields unchanged. status: COMPLETED marks it done. Same age/ownership guardrail as note updates |
HubSpot Static Lists (admin-scoped)
Push a BDR segment to a HubSpot static (MANUAL) list instead of CSV/Sheets import. Created list names are stamped with an [AI] prefix so humans can spot agent-managed lists in the UI.
| Tool | What it does |
|---|
hubspot_search_lists | Read. Find lists by query (substring) or exact name (case-insensitive). Returns listId (ILS), name, processingType, size. objectType: contacts/companies/deals |
hubspot_list_members | Read. List a list's members + their contact fields (name/email/company/jobtitle/phone) with per-member gap flags (blank jobtitle/phone) + summary. gapsOnly: true returns just the members needing enrichment. Use with enrich_contact to fill only the gaps (e.g. what the HubSpot/Breeze agent left partially filled) — saves Clay credits, doesn't re-enrich complete contacts. Works on any list |
hubspot_create_list | Create a MANUAL list. Idempotent — dedupes by name (forced [AI] prefix). Optional recordIds seed (max 5,000, auto-chunked ≤500/request). Reuses an existing agent-owned list; on a name clash with a human-made list it returns the ID but refuses to seed (LIST_NOT_AGENT_OWNED) |
hubspot_update_list_membership | Add/remove records (add/remove, combined max 5,000, auto-chunked into ≤500/request). Only on lists the agent created itself — refuses any other list (LIST_NOT_AGENT_OWNED) and non-MANUAL lists (LIST_NOT_MANUAL). Natively idempotent (already-member / non-member IDs reported as missing); a mid-batch failure returns PARTIAL_FAILURE with what landed — just re-run |
Why the ownership lock: a static-list membership can be a HubSpot workflow enrollment trigger. The agent can only mutate lists it created — so it can never inject members into a human-curated list that might fire a campaign. Lists created here are immediately queryable by the official HubSpot connector via hs_crm_search.ilsListIds.
Note: Stripe Cloud usage queries (renewals/growth/churn) go through ask_agent — there's no dedicated MCP tool. Just ask in natural language.
Namespaces — default to Epiphan Ai
Two MCP connections may show up:
Epiphan Ai — the full toolset above. Default to this.Epiphan CRM — a subset. Missing, among others: hubspot_get_contact, crm_get_customer_orders, get_upcoming_meetings, weekly_brief, hubspot_search_contacts, and the collaborator_owner_id filter on hubspot_search_deals.
If a tool seems "missing," you're probably on Epiphan CRM — switch to Epiphan Ai. (hubspot_search_contacts exists — it just isn't exposed on the CRM subset.)
Creating customer-facing assets → use the epiphan-brand-assets skill
Brand lives on a separate Epiphan Brand MCP server (voice, tokens, personas, product positioning, logos, fonts) and has its own dedicated skill. Before drafting any customer-facing asset (email, one-pager, deck, proposal) — and before any external send — defer to the epiphan-brand-assets skill, which drives the brand tools (get_brand_asset_kit, check_my_copy, …) end-to-end. Don't hand-roll brand calls from this CRM guide.
Good to Know
- Start with
ask_agent — it handles most questions including calls, products, revenue. Use specific tools only for direct lookups.
- Call search works by name — "how did the Tufts call go?" finds it via company/contact name (not just email).
- Product questions —
ask_agent uses product catalog + RAG. For pricing it pulls live CRM prices.
- Fuzzy matching works — don't worry about exact spelling for company names.
qualify_lead is a dry run by default — pass writeToHubSpot: true to update lifecycle + create the note (admin-scoped).ae_handoff with createNote: true — visible to the entire sales team.- HubSpot IDs are strings, CRM IDs are numbers.
- First
enrich_contact call for a new person takes 30-90s (Clay API). Subsequent calls are instant.
- Clari
clari_get_call — skip includeTranscript for faster responses.
- Be specific about time periods — "2024", "last 6 months", "Q3 2025".
- Specify metrics — "revenue", "order count", "average order value".
- Specify grouping — "by country", "by month", "by product family".
<success_criteria>
