Engagement overview

What it does

Real reading time + scroll depth from the engagement beacon (fired on pagehide). Returns engaged_pages count, avg/median/p90 engagement seconds, and avg/median scroll depth. avg_scroll_depth_pct and median_scroll_depth_pct are percentages of page height: 58.3 means 58.3% scrolled. Better signal than session duration which counts inactive tabs.

Example prompts

Ask Claude (or any MCP client connected to mcp-analytics) something like:

How engaged are mysite.com visitors? Scroll depth and time on page.

The client will pick engagement_overview automatically based on the prompt and your account's available sites.

Arguments

Name	Type	Required	Description / Default
site_id	string	required	Site identifier from list_sites (8-character base32, e.g. 'wjxayhdd').
period	string	optional	Time window. Keywords: today, yesterday, last_N_days (N from 1 to 730: today plus the N-1 days before, e.g. last_7_days, last_28_days), last_24_hours, this_week, last_week (weeks start on Monday), this_month, last_month, this_year, last_year, last_12_months. Or a custom date range YYYY-MM-DD..YYYY-MM-DD (inclusive). Days follow the site's timezone (list_sites; echoed as `timezone` in every response). default: last_7_days
conversion_event	string	optional	Optional custom event name (case-sensitive, from list_events) to treat as the conversion. The response then adds `converters`: the same engagement stats restricted to units that fired the event — compare it against the top-level stats to see whether converters read longer or scroll deeper. The response gains a site-wide `conversion` block: conversion_base (units in the period), converted (how many fired the event), conversion_rate (ratio 0–1: 0.05 means 5%), `unit` and a `note` to relay. The unit depends on the site's privacy_mode: 'session' on strict and balanced sites (no identity survives UTC midnight there, so only conversions within one visit count), 'visitor' on privacy_mode=all sites (first-party cookie, so a visitor who arrives Monday and converts Thursday counts as converted, if both days are inside the period). The auto-tracked 'pageview' and 'engagement' are rejected — pick one of the site's own events. Revenue: if the event carries a numeric `revenue` property (optional `currency`), the block gains revenue_total (over the converted units), currency (null when none was sent) and revenue_events (events with a numeric value; other values are ignored). Values are as reported by the site, not verified; negative values (refunds) are summed as sent. Only three-letter currency codes count as a currency; other values are unspecified. With two or more codes nothing is converted or added across codes: revenue_total, revenue_events and the rows' revenue cover the dominant code (most distinct converting units; itself visitor-influenced) plus values without a code, and the block adds revenue_by_currency listing each code with its own count. Not available with conversion_path.
conversion_path	string	optional	Optional goal page, the alternative to conversion_event (pass one, not both): a unit counts as converted if it has a pageview on this path anywhere in the period, so no custom event is needed and it works on past data. '/thank-you' matches that path exactly (a trailing slash on either side is ignored); a trailing * matches by prefix ('/checkout/success*'). Must start with '/'. Matched case-sensitively against the stored path, which has no query string and stores credential-like segments (long random tokens, UUIDs) as [redacted], so a goal containing one never matches. Only pageviews count: an engagement beacon or custom event on that page does not. Fields, unit (session, or visitor on privacy_mode=all sites) and the `conversion` block are as for conversion_event; the block names `path` and `match` (exact or prefix) instead of `event`. Filters narrow the units; the goal pageview counts anywhere in the period.
filters	object	optional	Optional segment filter. All given keys must match (AND; no OR, no negation); an empty string means not set. Keys: path (exact) or path_prefix; device_type, browser, os (exact, case-sensitive); referrer_host, utm_source, utm_medium, utm_campaign (exact); channel (search, ai_assistant, social, email, paid, campaign, referral, direct; as top_referrers group_by: channel assigns it). path/path_prefix match rows: pageviews count rows on matching paths, sessions/visitors count those with at least one matching row, and bounce_rate/avg_session_duration_seconds use all rows of those sessions. referrer_host, utm_* and channel match the session's entry (its first pageview in the period) and then select every row of the matching sessions, in every privacy mode. In top_entry_pages, top_referrers, top_sources and get_overview's top_source, path/path_prefix also test the entry: path_prefix '/blog/' there means sessions that entered on /blog/. Source and device filters make every number browser-only: server-side-ingested rows (including AI-mediated ai_user_action) have no session and no device fields, so they never match; the response then adds a `filter_note`. In get_overview, bot_share is null under any key other than path/path_prefix. With conversion_event the filter narrows the units; the conversion itself still counts anywhere in the period. The applied filters are echoed back as `filters`.

How to call it directly

If you're integrating from your own code rather than a chat client, this is the JSON-RPC payload:

curl -X POST https://mcp-analytics.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "engagement_overview",
    "arguments": {
      "site_id": "abc12345"
    }
  }
}'

Token comes from /settings after you sign up. Replace any required arguments above.

Related tools

• top_entry_pages: Landing pages: the URL path each session entered the site on.
• top_bots: Named-bot breakdown: which crawlers fetched the site, by canonical bot name (GPTBot, ClaudeBot, PerplexityBot, Googlebot, ...) with their traffic_class and hit counts.
• top_sources: Top UTM source/medium/campaign combinations.
• top_movers: What changed between two periods: the rows of one dimension that grew or shrank the most, in one call instead of diffing two list calls.
• top_languages: Top browser languages (de-DE, en-US, ...) of visitors.