MCP tools for analytics and optimization

Use these MCP tools to read dashboard totals, traffic sources, audience overlaps, and segment engagement. They can also retrieve the optimization catalog. They do not publish configuration, change a visitor, or run a suggested optimization. Dates, membership definitions, and unavailable-data behavior differ between reports, so their totals aren't interchangeable.

MCP analytics access and examples

Project reports accept an optional string project_id. You need an authorized MCP connection and access to the selected project. Invalid IDs, missing project selection, inaccessible projects, and disabled MCP access return errors.

get-optimization-playbook is a catalog read with no project argument. The other operations read collected events, not simulated traffic from an unpublished draft. Name enrichment can use current configuration labels.

Examples are illustrative and were not executed. Requests are parameters for MCP tools/call. Responses show decoded payloads; excerpts are labeled. Dates and numbers are synthetic.

get-analytics-overview

Returns the dashboard's core survey, enrichment, offer, and campaign metrics with time series.

Requested ranges longer than 30 days are truncated to the last 30 days ending at date_to. The response adds date_range_note when truncated. Request a short, explicit range rather than assuming this is an unlimited historical export.

{"name":"get-analytics-overview","arguments":{"project_id":"123456789","date_from":"2026-10-01T00:00:00Z","date_to":"2026-10-13T00:00:00Z","timezone":"UTC"}}

Illustrative response excerpt:

{"totalAnswers":48,"totalRespondents":30,"answersData":[{"x":"2026-10-12T00:00:00Z","y":48}],"respondentsData":[{"x":"2026-10-12T00:00:00Z","y":30}],"exposures":[{"holdback":false,"result":100},{"holdback":true,"result":100}],"conversions":[{"holdback":false,"result":15},{"holdback":true,"result":12}]}

The complete response fields are:

Enrichment timeSeries items contain key, subscribersEnriched, and dataPointsEnriched. Offer and question report objects have visitorsExposed, visitorsConverted, and timeSeries entries containing x, visitorsExposed, and visitorsConverted. They add offerBreakdowns or questionBreakdowns, with the same counts/series plus offerId or questionId. Recognized IDs can receive _name companions.

Date/timezone parsing can fail. Some dashboard service failures use empty arrays or zero-valued fallback metrics, including unavailable campaign reports. A successful response containing zeros is therefore not sufficient evidence that tracking and every report backend are healthy. This operation has no configuration side effect.

get-audience-breakdown

Builds a date-and-traffic-filtered visitor cohort, then reports those visitors' current segment membership and cross-dimension overlaps.

The declared overlap item schema permits strings or numbers, but runtime validation requires strings. Two IDs select their exact cross-tab; omitting them returns top overlaps across dimensions. IDs are validated against published dimensions, with draft fallback only when no published configuration exists.

Cohort filter schema

Values within a filter key are OR alternatives. Different keys combine with AND. Unknown keys are rejected.

An empty filter object means no filters. Empty arrays for supplied filter keys are invalid. There are no nested and/or objects, segment-ID filters, or free-text expressions.

{"name":"get-audience-breakdown","arguments":{"project_id":"123456789","date_from":"2026-10-01T00:00:00Z","date_to":"2026-10-13T00:00:00Z","filters":{"countries":["US"],"visited_pages":["/pricing"]},"overlap_dimension_ids":["dim_business","dim_need"],"min_visitors":5,"limit":20}}

Illustrative response excerpt:

{"cohort":{"matchedVisitors":100,"classifiedVisitors":80,"unclassifiedVisitors":20,"dateFrom":"2026-10-01T00:00:00+00:00","dateTo":"2026-10-13T00:00:00+00:00","membership":"current","filters":{"countries":["US"],"visited_pages":["/pricing"]}},"dimensions":[],"overlaps":[]}

The envelope contains cohort, dimensions, and overlaps:

• cohort has the fields shown. The time window selects activity; membership: "current" means membership is read now, not reconstructed as it was on each historical date.
• Each dimension has dimensionId, dimensionName, totalVisitors, coveragePct, and segments. Segment entries have segmentId, segmentName, visitors, percentOfClassifiedAudience, and percentOfDimension.
• Each overlap has firstDimensionId, firstDimensionName, firstSegmentId, firstSegmentName, the corresponding four second... fields, visitors, percentOfClassifiedAudience, percentOfFirstSegment, percentOfSecondSegment, and liftPct.

Responses are cached for five minutes. Queries are bounded to 500,000 pageviews and 100,000 cohort visitors, with a backend search timeout. Invalid dates, unknown dimensions, invalid filter shapes, excessive cohorts, and incomplete/failed analysis return errors rather than a made-up empty audience. Narrow the date range or filters when a query exceeds these limits. This operation does not change memberships or configuration.

get-traffic-analytics

Returns selected website traffic breakdowns.

The declared section-item schema allows strings or numbers; use the exact recognized names below. An unknown visitor-type string does not apply a visitor-type filter, so do not rely on it being rejected.

{"name":"get-traffic-analytics","arguments":{"project_id":"123456789","date_from":"2026-10-01T00:00:00Z","date_to":"2026-10-13T00:00:00Z","sections":["visitorType","referrers"],"limit":10}}

{"visitorType":{"anonymous":80,"subscribers":20,"suspectedBots":3},"referrers":[{"domain":"example.com","count":60}]}

The response is an object containing selected recognized section keys, without an additional data envelope:

The report uses a five-minute cache. Queries above the 500,000-pageview bound or incomplete/timed-out backend responses return errors. Reduce the range or select fewer sections when needed. This operation does not change configuration or visitor data.

get-segment-engagement

Compares each segment with the other classified visitors in the same dimension, using page engagement or conversion rate.

{"name":"get-segment-engagement","arguments":{"project_id":"123456789","date_from":"2026-10-01","date_to":"2026-10-12","basis":"engagement","dimension_ids":["dim_business"],"timezone":"UTC"}}

Illustrative response excerpt:

{"basis":"engagement","goalId":null,"offerId":null,"dateRange":{"start":"2026-10-01T00:00:00Z","end":"2026-10-12T23:59:59Z","timezone":"UTC"},"dimensions":[{"dimensionId":"dim_business","dimensionName":"Business type","baseline":2.4,"baselineVisitors":100,"segments":[{"segmentId":"seg_agency","segmentName":"Agency","uniqueVisitors":40,"value":3,"baseline":2,"liftPct":50,"confidence":"low","statusReason":null}]}],"leaderboard":{"best":[],"worst":[]}}

The envelope has basis, nullable goalId/offerId, dateRange, dimensions, and leaderboard. Dimensions have dimensionId, dimensionName, baseline, baselineVisitors, and segment entries. Segments have segmentId, segmentName, uniqueVisitors, value, baseline, liftPct, confidence, and statusReason. Conversion entries add converters.

engagement values are pages per visitor. Conversion values are proportions, such as 0.12 for 12%, not the percentage-unit values returned by split-test metrics. Segment baselines exclude that segment and use the other classified visitors in its dimension. Dimension-level baseline summarizes the dimension as a whole.

A nonpositive baseline makes liftPct null and confidence insufficient. statusReason distinguishes no_baseline_visitors, no_baseline_engagement, and no_baseline_conversions. Never turn null lift into a claimed 100% improvement. Confidence labels are sample-size bands: fewer than 30 is insufficient, 30–99 low, 100–499 medium, and 500+ high. They are not a significance test.

Engagement windows whose expanded start/end differ by more than 30 days are capped internally and add dateRangeCapped: true and maxEngagementDays: 30. The query starts at local midnight 30 calendar days before the end date, so the capped query can cover 31 inclusive calendar dates. The returned dateRange still describes the requested boundaries, not that adjusted start. Large segment membership can use up to 1,000 visitor IDs per segment; affected segment entries add isSampled: true and sampleSize. Use these fields when describing precision.

This MCP tool disables overlap leaderboards, returning empty best/worst arrays. The service applies min_visitors to leaderboard combinations, not the main segment rows, so do not assume this argument excludes low-count segments in this tool's response. Apply your own reporting threshold to uniqueVisitors if needed.

Missing basis-specific IDs return explicit errors. Unknown basis strings fall through to engagement calculation rather than reliable enum validation; send only the documented values. Goal measurement unavailable in published configuration returns empty results with goalTracking: "not-recorded". Reporting exceptions can also produce an empty response, so an empty result is not proof of zero engagement. Nonempty results are cached for five minutes. No configuration or visitor state is changed.

get-optimization-playbook

Lists active best-practice definitions that the recommendation system can detect. It does not run an account audit or return findings specific to your project.

The optional category string is normally fix, opportunity, or next_level. There is no project_id argument. Omit the category for all active practices. An unmatched value returns no practices rather than an enum error.

{"name":"get-optimization-playbook","arguments":{"category":"fix"}}

Illustrative response with no matching active practices:

{"total":0,"categories":{"fix":"Something is broken or severely underperforming","opportunity":"Leaving value on the table — could be significantly better","next_level":"Advanced usage or unexplored features"},"practices":[]}

Each practices item has practice_id, category, what_it_detects, effort, and tier_requirement. Results are ordered by category and practice ID. The categories descriptions remain present even for a filtered or empty result. Availability and text come from the current active catalog; this reference does not promise a fixed practice count.

This read has no project-selection step, provider request, draft mutation, or live-site effect. A recommendation definition is not evidence that the condition exists in your project.