What it does

Top UTM source/medium/campaign combinations. Attribution metric — counts direct browser visits only ('user' class). AI-mediated traffic loses original UTM tags so it would only add noise. Counted once per session (field `sessions`), from the UTM tags the session entered on — not once per pageview, so don't compare it against pageview counts. Each row also has bounce_rate (ratio 0–1 of the row's sessions with exactly one pageview and no custom event; the engagement beacon does not count) and avg_session_duration_seconds (first to last event, over the row's sessions with more than one event; null when there is none).

Example prompts

Ask:

"Which UTM source brought the most visits to mysite.com last month?"
"Top traffic sources by campaign, last 90 days."
"How did the spring_launch campaign actually perform?"

A typical response:

Top sources (last 30 days):

  newsletter    weekly       spring_launch    1,847 sessions
  twitter       social       (none)             612 sessions
  google        cpc          search_brand       487 sessions
  reddit        social       (none)             302 sessions
  google        cpc          search_generic     224 sessions
  podcast       referral     dev_tools_pod      174 sessions
  hackernews    referral     (none)             142 sessions
  newsletter    weekly       summer_promo       102 sessions
  (none)        organic      (none)              89 sessions

Returns groups of { utm_source, utm_medium, utm_campaign, sessions }. Counted once per session, from the source the session entered on — not once per pageview. Useful for evaluating whether a specific UTM-tagged campaign actually delivered, or for spotting that your newsletter is your highest-quality referral source.

Attribution metric: direct browser visits only. AI-mediated traffic loses original UTM tags entirely (an AI fetching a page doesn't preserve the user's original UTM-tagged click), so including it would add noise without signal. See traffic_class_breakdown for the per-class breakdown.

To see which channels drive conversions, not just visits, pass conversion_event (one of your custom events, e.g. signup): each row gains the share of its sessions (visitors, on sites in privacy mode all) that fired it during the period. For landing pages instead of channels, use top_entry_pages the same way. For built-in dimensions (browser, OS, device type), breakdown is the right tool.

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
limit integer optional Maximum number of rows to return. Capped at 1000 server-side.
default: 10
conversion_event string optional Optional custom event name (case-sensitive, from list_events) to treat as the conversion. Each row then gains conversion_base (units in that row), converted (how many of them fired the event anywhere in the period) and conversion_rate (ratio 0–1: 0.05 means 5%; null when no unit is attributed to the row: it has no browser sessions/visitors at all, e.g. purely server-ingested traffic, or — on privacy_mode=all sites in top_referrers/top_sources/top_entry_pages — the row was never any visitor's first entry in the period, even though it has sessions). 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. Use it to compare conversion rates between rows — absolute counts alone favour whatever row has the most traffic. 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`, e.g. mcpa('track', 'purchase', { revenue: 149, currency: 'EUR' })), each row gains revenue (sum over the conversion events of the units in that row; like conversion_base, not additive across rows where a unit appears in several) and revenue_per_unit (revenue / conversion_base), and 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": "top_sources",
    "arguments": {
      "site_id": "abc12345"
    }
  }
}'

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

Related tools

  • breakdown: Breakdown of visits by browser, os, device_type, or country (country empty in MVP).
  • add_site: Register a new site.
  • event_details: Details for one event.
  • top_entry_pages: Landing pages: the URL path each session entered the site on.
  • top_user_agents: Top User-Agent strings with their traffic_class.