Warmly MCP Server

List recent warm visitors (identified people who visited the org website) with session aggregations and profile info. Window: default past_day, max past_month (30 days). take clamped to 500. DATA FRESHNESS: • Live/near-real-time — read straight from the WarmSession table (the session data store) on each call. There is no batch or scheduled refresh; results reflect current data. • The newest sessions are held back by a post-session settle window (default ~60 min, configurable) before they surface, and reads go through a read replica, so brief replication lag also applies. FILTERS: • searchTerm — substring match against name/email/company name. • requireBusinessContact — when true, keeps only visitors with a LinkedIn handle AND a work email (excludes personal-email leakage). NOT an ICP segment filter despite the legacy name "icpOnly" — true ICP filtering is segment-based and not exposed via this tool yet. • countries — array of ISO-3166-1 alpha-2 codes (e.g. ["US", "GB"]). Case-insensitive. Matches the visitor's resolved company country (ClearbitCompany.geo_countryCode), not the contact's location. • industries — array of free-form industry strings (case-insensitive). See ALLOWED INDUSTRIES below for the high-coverage list; other strings are accepted but may match zero rows. • employeeSizeBands — array of Apollo-style company-size bands. Strict text-equality match against ClearbitCompany.metrics_employeesRange. Coverage caveat: this column is populated by multiple enrichers with inconsistent formats — a band you pass may not match data stored as a variant (e.g. "51-100" vs "51-200"). If your filter returns zero, try a broader band or omit. • Allowed employeeSizeBands values (pass exactly as listed): 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+. • Top industries by row volume (any string accepted; this list covers the high-coverage values): Software, Computer Software, Information Technology and Services, Internet, Financial Services, Marketing and Advertising, Hospital & Health Care, Telecommunications, Education Management, Computer & Network Security, Management Consulting, Real Estate, Retail, Banking, Insurance, E-Learning, Higher Education, Consumer Services, Construction, Manufacturing, Pharmaceuticals, Biotechnology, Medical Devices, Logistics and Supply Chain, Renewables & Environment, Wholesale, Automotive, Apparel & Fashion, Food & Beverages, Restaurants, Hospitality, Leisure, Travel & Tourism, Media Production, Online Media, Publishing, Entertainment, Computer Games, Sporting Goods, Health, Wellness and Fitness, Mental Health Care, Architecture & Planning, Civic & Social Organization, Non-Profit Organization Management, Religious Institutions, Government Administration, Legal Services, Law Practice, Staffing and Recruiting, Human Resources, Accounting. • segmentIds — array of WarmOpps segment ids. Filters to visitors matching the org's saved segment(s) using the segment's own criteria. Get ids from the list_segments tool (do NOT guess — these are UUIDs). When set, countries / industries / employeeSizeBands are ignored (the segment definition governs matching); searchTerm and timeWindow still apply. CAVEATS: • contact.phone_number always returns null until ENG-6943 wires the source. • pages_visited_contains is accepted but not yet enforced server-side (ENG-6943). RENDERING: When presenting results to the user, render a Markdown table using `defaultView.columns` in order and `defaultView.rows` (one row per item, same order as `results`). Each cell has been pre-formatted server-side: composite cells (`two_line`, `dot_separated`, `badge`) are ready strings; `link_icons` is an object of URLs; `indicator` is a single glyph or null. Additional per-row fields are available in the raw `results` array and can be surfaced on follow-up questions ("tell me more about row 3").

List recent warm accounts (companies whose visitors hit the org website) with session aggregations and profile info. Window: default past_day, max past_month (30 days). take clamped to 500. DATA FRESHNESS: • Live/near-real-time — read straight from the WarmSession table (the session data store) on each call. There is no batch or scheduled refresh; results reflect current data. • The newest sessions are held back by a post-session settle window (default ~60 min, configurable) before they surface, and reads go through a read replica, so brief replication lag also applies. FILTERS: • searchTerm — substring match against domain / company name. • countries — array of ISO-3166-1 alpha-2 codes (e.g. ["US", "GB"]). Case-insensitive match against ClearbitCompany.geo_countryCode. • industries — array of free-form industry strings (case-insensitive). See ALLOWED INDUSTRIES below for the high-coverage list; other strings are accepted but may match zero rows. • employeeSizeBands — array of Apollo-style company-size bands. Strict text-equality match against ClearbitCompany.metrics_employeesRange. Coverage caveat: this column is populated by multiple enrichers with inconsistent formats — a band you pass may not match data stored as a variant. If your filter returns zero, try a broader band or omit. • Allowed employeeSizeBands values (pass exactly as listed): 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10000+. • Top industries by row volume (any string accepted; this list covers the high-coverage values): Software, Computer Software, Information Technology and Services, Internet, Financial Services, Marketing and Advertising, Hospital & Health Care, Telecommunications, Education Management, Computer & Network Security, Management Consulting, Real Estate, Retail, Banking, Insurance, E-Learning, Higher Education, Consumer Services, Construction, Manufacturing, Pharmaceuticals, Biotechnology, Medical Devices, Logistics and Supply Chain, Renewables & Environment, Wholesale, Automotive, Apparel & Fashion, Food & Beverages, Restaurants, Hospitality, Leisure, Travel & Tourism, Media Production, Online Media, Publishing, Entertainment, Computer Games, Sporting Goods, Health, Wellness and Fitness, Mental Health Care, Architecture & Planning, Civic & Social Organization, Non-Profit Organization Management, Religious Institutions, Government Administration, Legal Services, Law Practice, Staffing and Recruiting, Human Resources, Accounting. • segmentIds — array of WarmOpps segment ids. Filters to accounts matching the org's saved segment(s) using the segment's own criteria. Get ids from the list_segments tool (do NOT guess — these are UUIDs). When set, countries / industries / employeeSizeBands are ignored (the segment definition governs matching); searchTerm and timeWindow still apply. CAVEATS: • pages_visited_contains is accepted but not yet enforced server-side (ENG-6943). RENDERING: When presenting results to the user, render a Markdown table using `defaultView.columns` in order and `defaultView.rows` (one row per item, same order as `results`). Each cell has been pre-formatted server-side: composite cells (`two_line`, `dot_separated`, `badge`) are ready strings; `link_icons` is an object of URLs; `indicator` is a single glyph or null. Additional per-row fields are available in the raw `results` array and can be surfaced on follow-up questions ("tell me more about row 3").

List the calling organization's saved WarmOpps segments (named, reusable filter definitions). Use this to translate a segment NAME the user mentions into the segment `id` accepted by list_warm_visitors / list_warm_accounts via their `segmentIds` input — e.g. "warm visitors in the Enterprise Funding segment that came by today" → call list_segments, find the id whose name matches, then call list_warm_visitors with segmentIds=[that id] and timeWindow=past_day. FILTERS: • searchTerm — case-insensitive substring match against the segment name. Free metadata lookup — never charges a credit.

Returns how many MCP / External API credits the calling organization has remaining for the current billing month. Free metadata lookup — never charges a credit.

Aggregate inbound-chat performance metrics for a date range — counts of greetings, engagement, emails captured, and book-a-meeting clicks. PII-free aggregates only. WINDOW: • startDate / endDate are ISO strings; a bare date like 2026-05-15 covers that whole day (UTC). • Defaults to the last 7 days. Ranges over 92 days are rejected — split a longer look-back into multiple calls. GROUP BY (the `groupBy` arg): • overall — one org-wide metric set (the full breakdown: chats, bot/rep greeted, engaged, missed, connected, alerted, emails, meeting clicks). • workflow — per inbound workflow (which workflows perform best). • ai_agent — per AI greeting / AI Studio agent that handled the chat (which greeting groups perform best). • page — per entry page the visitor landed on (which pages drive engagement). • utm_source — per entry utm_source (which campaigns/sources drive engagement). • Grouped views return the top 50 groups by session volume; isTruncated=true means more groups exist (narrow the date range). DEFINITIONS (same rules as the in-app Chat Reports): • greeted — bot or rep sent a greeting. visitorEngaged — visitor replied or clicked a link. • emailCaptured — visitor typed an email in chat. bookMeetingClicked — visitor clicked a calendar / book-a-meeting link. • engagementRate = visitorEngaged / sessions, conversionRate = emailCaptured / sessions (fractions, 0–1). For an individual chat list use list_chats; for one conversation’s messages use get_chat_transcript. RENDERING: When presenting results to the user, render a Markdown table using `defaultView.columns` in order and `defaultView.rows` (one row per item, same order as `results`). Each cell has been pre-formatted server-side: composite cells (`two_line`, `dot_separated`, `badge`) are ready strings; `link_icons` is an object of URLs; `indicator` is a single glyph or null. Additional per-row fields are available in the raw `results` array and can be surfaced on follow-up questions ("tell me more about row 3").

List individual inbound-chat sessions for a date range, one row per chat with visitor, workflow, assigned rep, and visitor-message count. Use to drill into the chats behind a metric, or to collect sessionIds for get_chat_transcript. WINDOW: • startDate / endDate are ISO strings; a bare date like 2026-05-15 covers that whole day (UTC). • Defaults to the last 7 days. Ranges over 180 days (~6 months) are rejected. FILTERS: • metricKey — restrict to one chat category. Defaults to `chats` (rep-handled). Notable values: `emails` (visitor left an email), `cal_clicked` (clicked a book-a-meeting link), `visitor_engaged` (visitor replied or clicked), `missed` (engaged but no rep picked up), `connected` (rep engaged a responding visitor). • workflowIds — restrict to sessions that ran the given inbound workflow(s) (UUIDs). • userIds — restrict to chats a given rep (UUID) participated in. • take — page size (default 25, max 200). offset — page start. isTruncated=true means a full page came back and more may exist; raise offset to page. For aggregate counts/breakdowns use get_chat_metrics; for one conversation’s messages use get_chat_transcript. RENDERING: When presenting results to the user, render a Markdown table using `defaultView.columns` in order and `defaultView.rows` (one row per item, same order as `results`). Each cell has been pre-formatted server-side: composite cells (`two_line`, `dot_separated`, `badge`) are ready strings; `link_icons` is an object of URLs; `indicator` is a single glyph or null. Additional per-row fields are available in the raw `results` array and can be surfaced on follow-up questions ("tell me more about row 3").

Read the full message transcript of one inbound-chat session — every visitor and agent turn in order, with content, role, and timestamp. Use after list_chats (or a metric breakdown) to read what was actually said — e.g. to judge intent or why a chat did/did not convert. Input is a single sessionId (UUID). Read-only; returns "not found" for a session that is not in your organization.

Read the page-visit timeline for one inbound-chat session — the pages the visitor browsed before/during the chat, in order (url, pathname, timestamp). Use to see where a specific visitor came from and what they looked at. For an org-wide page/UTM breakdown use get_chat_metrics with groupBy page or utm_source instead. Input is a single sessionId (UUID). Read-only; returns "not found" for a session that is not in your organization.