What it does

Details for one event. Without group_by_property the response lists the event's observed custom properties in `properties` (name, occurrences, distinct_values — ordered by occurrences, capped at 50), so a follow-up call can pick a real property name. With group_by_property the response is `items` with the top 100 property values by count (a high-cardinality property is truncated at 100 — the counts then cover those rows only, not the event total); if that property was not observed on this event in the period, `items` is empty and the response adds `note` plus `observed_properties` (the names the event actually carries) instead of leaving an empty list ambiguous. An unobserved property is not proof it does not exist — an earlier period may still carry it. Volume metric — counts include AI-mediated human browsing (ai_user_action). `sessions_with_event` counts browser sessions only, since server-side-ingested rows carry no session, so it can be 0 while `total_count` is not. If the event carries a numeric `revenue` property, the ungrouped response adds revenue_total, revenue_avg (per event with a numeric value), revenue_events and currency (null when none was sent), counted over the event's rows like total_count, as reported by the site (not verified); with two or more currency codes revenue_by_currency replaces revenue_total, revenue_avg and currency, and revenue_events then spans every code (unlike the conversion block, where it follows the dominant code).

Example prompts

Ask:

"Show me details for the signup_started event on mysite.com last 30 days."
"How is the signup_started event split by plan?"
"For the demo_booked event, group by the rep property."

A typical response, grouped by the custom plan property:

Event signup_started, last 30 days, grouped by plan:

  free       182 events
  pro         64 events
  (not set)   14 events

Returns event counts segmented by a property of your choice. The group_by_property argument slices by custom event properties only: any key you attach when firing the event (e.g. plan, variant, source). For built-in dimensions like browser or device type, use breakdown instead; for referrers and UTM tags, use top_referrers and top_sources.

Volume metric: counts include AI-mediated human browsing if the event was fired from a Claude/ChatGPT-fetched page.

To fire custom events from your JS:

window.mcpa('track', 'signup_started', {
  plan: 'pro',
  source: 'pricing_cta'
});

Custom events are a client-side thing: they fire from the visitor's browser via the snippet above. There is also a server-side ingest endpoint (POST /ingest/server, authenticated with your site's ingest secret from /settings), but it exists to capture what the JS snippet can't see: AI crawlers and bots that never execute JavaScript. Human traffic is deliberately dropped on that path so the JS beacon and the middleware don't double-count. Don't route human conversion events through it.

List all event names with list_events first if you're not sure what's being tracked — its response also includes each event's observed property names, so you don't have to guess what to group by. If you pass a property the event doesn't carry, the response says so explicitly (with the properties it does carry) instead of returning a bare empty list.

Arguments

Name Type Required Description / Default
site_id string required Site identifier from list_sites (8-character base32, e.g. 'wjxayhdd').
event_name string required Custom event name to drill into (case-sensitive). Use list_events to discover available event names. 'pageview' is the auto-tracked default; anything else came from a mcpa('track', name, props) call in the customer's site code.
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
group_by_property string optional Optional name of a custom property to slice the event by. Example: if events were tracked with mcpa('track', 'signup', {plan: 'pro'}), pass 'plan' here to see counts per plan value.
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": "event_details",
    "arguments": {
      "site_id": "abc12345",
      "event_name": "signup_started"
    }
  }
}'

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

Related tools

  • top_pages: Most-viewed URL paths.
  • remove_site: Soft-delete a site.
  • top_sources: Top UTM source/medium/campaign combinations.
  • get_account: Account info — email, current plan, total active sites, total_hits_this_month (across all sites), plan_limit, and api_token_first_chars (first 10 chars of the legacy API token, for identification only — not enough to authenticate).
  • add_site: Register a new site.