MCP tools for visitor search, activity, and profiles

Use these MCP tools to find visitors, read their activity, and retrieve profiles from data collected for your project. They do not identify arbitrary anonymous visitors, change segments, or contact a visitor. Profile lookup can make an external request to your connected email platform.

MCP visitor access and privacy

Every operation accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. Invalid IDs, unresolved selection, inaccessible projects, and unavailable MCP access return errors.

Resource names are resolved from draft configuration first, then published configuration. The underlying activity is collected data, not a simulation of draft behavior. A draft name shown beside a historical event is not proof that the draft was live when the event occurred.

Results can include addresses, free-text responses, provider fields, and browsing history. Request only what is needed and do not forward it to an unrelated destination. Examples below are illustrative and were not executed. They show tools/call parameters and decoded response payloads.

search-visitors

Finds recently active visitors, with optional audience, resource, and event filters.

Recognized event types are pageview, offer_conversion, offer_exposure, answer, question_exposure, campaign_exposure, and campaign_conversion. There are no cursor, offset, or nested filter arguments.

{"name":"search-visitors","arguments":{"project_id":"123456789","start":"2026-10-01T00:00:00Z","end":"2026-10-13T00:00:00Z","limit":25,"visitor_type":"identified","offer_id":"ofr_example"}}

Illustrative response with no matches:

{"visitors":[],"total":0,"dateRange":{"from":"2026-10-01T00:00:00+00:00","to":"2026-10-13T00:00:00+00:00"},"fetchTime":"2026-10-13T12:00:00+00:00"}

Normal search response

The response contains visitors, total, dateRange: {from,to}, and fetchTime. A visitor entry includes:

• visitorId and personIdentity: {type,value}, where type is email or visitorId.
• firstSeen, lastSeen, pageviewCount, visitCount, and eventCount.
• Nullable arrival: {url, referrer}, with nullable URL strings when arrival enrichment is available.
• profile, including emailAddress, isSubscriber, segmentIds, and any collected customFields.
• botScore and up to ten recentEvents on the event-aggregation path.

Recent event entries include index, indexType, timestamp, eventData, and nullable page, device, browser, and geo. The compact nested shapes are page.url: {pathname,hostname}, device: {type}, browser: {name}, and geo: {city,country}.

eventData.type identifies the event. Depending on type it can also contain offerId, questionId, segmentId, widgetId, campaignId, goalId, goalEventId, or isLeadCapture. Recognized resource IDs can receive _name companion fields. Resource-filtered totals can be cardinality estimates rather than exact counts.

Filter limitations

Use IDs for reliable targeting. Name resolution tries a case-insensitive exact match, then the first partial match. An unresolved name becomes a null filter and is dropped. It does not reliably produce an error or an empty result, so a misspelled name can broaden your search.

event_type filters the recent events on the already-retrieved visitor page, then removes visitors without matching recent events. Its resulting total is the count on that filtered page, not an exhaustive count of everyone who performed that event during the window.

When flow_id resolves, the tool uses only that flow, the dates, the limit, and whether visitor_type equals identified. It does not combine the other resource filters, search, or event_type. visitor_type: "anonymous" on this branch does not exclude identified visitors. Do not use a flow query as evidence that all supplied filters were applied.

Flow search response

Flow search returns {visitors, total}. Each visitor contains visitorId, nullable emailAddress, completionStatus, timestamp, durationMs, pageUrl, and nullable lastNode, the last recorded flow-node object. It does not return the normal search's recent-events/profile shape.

This operation does not change draft or live configuration. Date parsing and backend errors can fail a request. The flow search service can return an empty result after a backend exception, so an empty flow result alone does not prove that nobody executed the flow.

get-visitor-activity

Returns a paginated timeline of sessions and pageviews for one known identifier.

{"name":"get-visitor-activity","arguments":{"project_id":"123456789","identifier":"operator@example.com","limit":100}}

Illustrative empty response:

{"sessions":[],"total_pageviews":0,"total_sessions":0,"first_seen":null,"last_seen":null,"next_page_token":null,"has_more":false,"visitor_profiles":[]}

The top-level fields are exactly those shown before optional name enrichment. total_pageviews, total_sessions, first_seen, and last_seen describe the returned timeline page, not necessarily lifetime history. Pass next_page_token back as before to retrieve older activity. Keep limit at 100 or below. Above that, the response can report has_more: false despite a non-null cursor.

Session entries have startedAt, endedAt, pageviews, durationMinutes, nullable gapToNextSession: {seconds,formatted}, and hoisted device, browser, and geo metadata. Pageviews always contain timestamp and page, a combined hostname/path string. Nonempty values can add referrer, timeOnPageSeconds, flowExecutions, campaignActivity, and hasSyncEvent: true. Missing optional fields are not errors.

A simplified flow execution contains flowId, flowName, widgetId, widgetName, completionStatus, durationMs, and nodes. Node summaries are:

Root and internal routing nodes are omitted. These are activity summaries, not editable flow node definitions. visitor_profiles is keyed by visitor ID when populated and can contain emailAddress, isSubscriber, segmentIds, and customFields.

Missing identifiers return identifier is required. No activity can return the empty shape above rather than a not-found error. Invalid cursors or reporting failures can fail retrieval; some interaction-enrichment failures leave a timeline without that enrichment. The tool does not mutate the visitor, draft, or published configuration.

get-visitor-profile

Combines identity, current segmentation, free-text survey responses, a bounded activity summary, and optional provider contact data.

Arguments: optional project_id string and required identifier string. Identifier decoding and email detection match get-visitor-activity. There are no date, pagination, or include-provider flags.

{"name":"get-visitor-profile","arguments":{"project_id":"123456789","identifier":"operator@example.com"}}

Illustrative response excerpt:

{"identity":{"email":"operator@example.com","isSubscriber":true,"visitorIds":["visitor_example"],"firstSeen":"2026-10-12T10:00:00Z","lastSeen":"2026-10-13T10:00:00Z"},"segmentation":[{"dimensionId":"dim_example","dimensionName":"Business type","segments":[{"segmentId":"seg_agency","segmentName":"Agency"}]}],"activitySummary":{"totalSessions":2,"totalPageviews":3,"pagesPerSession":1.5,"topPages":[{"url":"example.com/","hostname":"example.com","pathname":"/","visits":2}]},"surveyResponses":[]}

The four main sections are:

• identity: nullable email, subscriber status, known visitor IDs, and first/last timestamps from the retrieved timeline.
• segmentation: dimensions with dimensionId, dimensionName, and segment objects containing segmentId/segmentName.
• activitySummary: totalSessions, totalPageviews, pagesPerSession, and up to five topPages entries with url, hostname, pathname, and visits.
• surveyResponses: up to 50 free-text response entries with timestamp, content, questionId, and optional questionName.

The activity summary reads at most 100 pageviews. Its counts and top pages are not an unlimited lifetime report. Segmentation uses current visitor profiles and configuration labels, not a historical reconstruction for each event.

When a known email can be looked up in the active provider, integrationData can include contactFound, integrationName, integrationLabel, provider, providerLabel, contactId, email, nativeFields, customFields, tags, and the provider's profile. Field/tag/profile values are provider-specific. A successful no-contact lookup returns contactFound: false with provider identity. A missing integration or lookup exception omits the section entirely, so omission is not proof that the provider has no contact.

This tool can call the external provider despite its read-only purpose. It does not modify that contact. Missing input returns an error; no collected identity or pageview data returns No visitor found for identifier: ... before attempting provider enrichment. No draft or publication state is changed.