Data Activation Visitors Server

Overview

The Data Activation Visitors Server specializes in analyzing identified visitor data. It helps you understand visitor behavior, session patterns, engagement metrics, and individual visitor journeys.

Server Details

Server Name: data-activation-visitors-server
Version: 0.0.1
Endpoint: /mcp/data-activation-visitors
Authentication: Organization-level required

Purpose

Analyze identified visitors, track their session behavior, engagement patterns, page views, and understand individual visitor journeys to identify high-value prospects and engagement opportunities.

Available Tools

1. visitors-schema-tool

Purpose: Get field mappings for the Visitors index

When to use: Before constructing queries to understand available fields

Returns: Elasticsearch mapping with field names, types, and descriptions

2. visitors-compute-tool

Purpose: Execute Elasticsearch queries against the Visitors index

Input: Elasticsearch query JSON Returns: Query results with matching visitors and aggregations

3. terminology-tool

Purpose: Translate abbreviations and business terms

4. visitor-links-tool

Purpose: Generate clickable links to visitor profiles

Input:

{
  "visitors": [
    {"id": "visitor-123", "label": "John Doe"},
    {"id": "visitor-456", "label": "Jane Smith"}
  ]
}

Returns: Array of clickable links to visitor detail pages

5. chart-format-tool

Purpose: Generate Chart.js configurations for visualizing visitor data

Key Fields

Identity Fields

id - Unique visitor identifier
email - Visitor email address
name - Visitor name
firstName - First name
lastName - Last name
title - Job title
phone - Phone number

Company Fields

company - Company name
companyDomain - Company domain
companyUuid - Associated company UUID

Session Fields

sessionId - Session identifier
sessionStart - Session start timestamp
sessionEnd - Session end timestamp
sessionDuration - Session duration (seconds)

Engagement Fields

pageViews - Number of page views
uniquePages - Number of unique pages visited
totalActiveTime - Total active time on site (seconds)
urls - Array of URLs visited
lastVisitDate - Most recent visit date
firstVisitDate - First visit date

Attribution Fields

utmSource - UTM source
utmMedium - UTM medium
utmCampaign - UTM campaign
utmContent - UTM content
utmTerm - UTM term
referrer - Referrer URL
landingPage - Landing page URL

Device/Location Fields

device - Device type (desktop, mobile, tablet)
browser - Browser name
os - Operating system
city - City
state - State/province
country - Country
ipAddress - IP address

Behavioral Fields

engagementScore - Engagement score
intentScore - Intent score
isIdentified - Whether visitor is identified
identifiedDate - When visitor was identified

Common Use Cases

1. Recently Identified Visitors

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"identifiedDate": {"gte": "now-7d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "identifiedDate", "pageViews"],
  "sort": [{"identifiedDate": "desc"}],
  "size": 50
}

2. High-Engagement Visitors

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 10}}},
        {"range": {"totalActiveTime": {"gte": 300}}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "pageViews", "totalActiveTime", "urls"],
  "sort": [{"pageViews": "desc"}],
  "size": 100
}

3. Visitors by Company

{
  "query": {
    "wildcard": {"companyDomain": "*acme.com"}
  },
  "_source": ["id", "name", "email", "title", "company", "pageViews", "lastVisitDate"],
  "sort": [{"lastVisitDate": "desc"}],
  "size": 50
}

4. Visitors Viewing Specific Pages

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"urls": "*pricing*"}},
        {"wildcard": {"urls": "*demo*"}},
        {"wildcard": {"urls": "*contact*"}}
      ],
      "minimum_should_match": 1,
      "filter": [
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "urls", "lastVisitDate"],
  "size": 100
}

5. Visitors by UTM Campaign

{
  "query": {
    "term": {"utmCampaign.keyword": "Q1-Brand-Campaign"}
  },
  "size": 0,
  "aggs": {
    "total_visitors": {
      "cardinality": {"field": "id.keyword"}
    },
    "identified_visitors": {
      "filter": {"term": {"isIdentified": true}}
    },
    "avg_page_views": {
      "avg": {"field": "pageViews"}
    },
    "avg_active_time": {
      "avg": {"field": "totalActiveTime"}
    }
  }
}

6. Visitor Engagement Trend

{
  "query": {
    "range": {"lastVisitDate": {"gte": "now-30d/d"}}
  },
  "size": 0,
  "aggs": {
    "visits_by_day": {
      "date_histogram": {
        "field": "lastVisitDate",
        "calendar_interval": "day"
      },
      "aggs": {
        "unique_visitors": {
          "cardinality": {"field": "id.keyword"}
        },
        "total_page_views": {
          "sum": {"field": "pageViews"}
        }
      }
    }
  }
}

7. Visitors by Job Title

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"title": "*director*"}},
        {"wildcard": {"title": "*vp*"}},
        {"wildcard": {"title": "*manager*"}}
      ],
      "minimum_should_match": 1,
      "filter": [
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "_source": ["id", "name", "email", "title", "company", "pageViews"],
  "size": 100
}

8. Visitors by Device Type

{
  "query": {
    "range": {"lastVisitDate": {"gte": "now-30d/d"}}
  },
  "size": 0,
  "aggs": {
    "by_device": {
      "terms": {"field": "device.keyword", "size": 10},
      "aggs": {
        "unique_visitors": {
          "cardinality": {"field": "id.keyword"}
        },
        "avg_page_views": {
          "avg": {"field": "pageViews"}
        },
        "avg_session_duration": {
          "avg": {"field": "sessionDuration"}
        }
      }
    }
  }
}

9. Visitors by Geographic Location

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"country.keyword": "United States"}},
        {"term": {"isIdentified": true}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_state": {
      "terms": {"field": "state.keyword", "size": 20},
      "aggs": {
        "visitor_count": {
          "cardinality": {"field": "id.keyword"}
        },
        "avg_engagement": {
          "avg": {"field": "engagementScore"}
        }
      }
    }
  }
}

10. High-Intent Visitors

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"intentScore": {"gte": 70}}},
        {"term": {"isIdentified": true}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "intentScore", "pageViews", "urls"],
  "sort": [{"intentScore": "desc"}],
  "size": 50
}

11. Session Analysis

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"sessionStart": {"gte": "now-7d/d"}}},
        {"range": {"sessionDuration": {"gte": 60}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "sessionId", "sessionStart", "sessionDuration", "pageViews"],
  "sort": [{"sessionDuration": "desc"}],
  "size": 100
}

12. Repeat Visitors

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 5}}},
        {"exists": {"field": "firstVisitDate"}},
        {"exists": {"field": "lastVisitDate"}}
      ]
    }
  },
  "size": 0,
  "aggs": {
    "by_visitor": {
      "terms": {"field": "id.keyword", "size": 100},
      "aggs": {
        "total_page_views": {
          "sum": {"field": "pageViews"}
        },
        "visit_count": {
          "value_count": {"field": "sessionId.keyword"}
        }
      }
    }
  }
}

Best Practices

1. Always Check Schema First

Call visitors-schema-tool before querying to ensure correct field names.

2. Use Wildcard for Text Search

Unless exact match is explicitly requested:

{"wildcard": {"name": "*john*"}}

3. Filter for Identified Visitors

For most analyses, focus on identified visitors:

{"term": {"isIdentified": true}}

4. Include Key Fields in _source

Always include: id, name, email, company for generating visitor links.

5. Use .keyword for Exact Matches

For text fields that need exact matching:

{"term": {"company.keyword": "Acme Corp"}}

6. Apply Date Filters

For time-sensitive queries:

{"range": {"lastVisitDate": {"gte": "now-30d/d"}}}

7. Generate Clickable Links

After retrieving visitors, call visitor-links-tool to provide easy access.

8. Combine Engagement Metrics

Use multiple engagement signals for better insights:

{
  "query": {
    "bool": {
      "filter": [
        {"range": {"pageViews": {"gte": 5}}},
        {"range": {"totalActiveTime": {"gte": 180}}},
        {"range": {"uniquePages": {"gte": 3}}}
      ]
    }
  }
}

Query Patterns

Multiple Filters Combined

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"pageViews": {"gte": 5}}},
        {"wildcard": {"title": "*director*"}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  }
}

Text Search Across Multiple Fields

{
  "query": {
    "bool": {
      "should": [
        {"wildcard": {"name": "*search*term*"}},
        {"wildcard": {"email": "*search*term*"}},
        {"wildcard": {"company": "*search*term*"}}
      ],
      "minimum_should_match": 1
    }
  }
}

Aggregations for Insights

{
  "size": 0,
  "aggs": {
    "engagement_distribution": {
      "histogram": {"field": "engagementScore", "interval": 10}
    },
    "top_companies": {
      "terms": {"field": "company.keyword", "size": 20}
    },
    "avg_metrics": {
      "stats": {"field": "pageViews"}
    }
  }
}

Sorting by Multiple Fields

{
  "sort": [
    {"intentScore": "desc"},
    {"pageViews": "desc"},
    {"lastVisitDate": "desc"}
  ]
}

Workflow Example

Goal: Find high-engagement visitors from target companies who viewed pricing pages

Step 1: Check schema

Call: visitors-schema-tool

Step 2: Query visitors

{
  "query": {
    "bool": {
      "filter": [
        {"term": {"isIdentified": true}},
        {"range": {"pageViews": {"gte": 5}}},
        {"wildcard": {"urls": "*pricing*"}},
        {"range": {"lastVisitDate": {"gte": "now-14d/d"}}}
      ]
    }
  },
  "_source": ["id", "name", "email", "company", "title", "pageViews", "urls", "lastVisitDate"],
  "sort": [{"pageViews": "desc"}],
  "size": 50
}

Step 3: Generate links

{
  "visitors": [
    {"id": "visitor-123", "label": "John Doe - Acme Corp"},
    {"id": "visitor-456", "label": "Jane Smith - TechCo"}
  ]
}

Step 4: Present results with insights

Show visitor names as clickable links
Highlight engagement metrics
Note pages viewed (especially pricing)
Provide recommendations for follow-up

Overview​

Server Details​

Purpose​

Available Tools​

1. visitors-schema-tool​

2. visitors-compute-tool​

3. terminology-tool​

4. visitor-links-tool​

5. chart-format-tool​

Key Fields​

Identity Fields​

Company Fields​

Session Fields​

Engagement Fields​

Attribution Fields​

Device/Location Fields​

Behavioral Fields​

Common Use Cases​

1. Recently Identified Visitors​

2. High-Engagement Visitors​

3. Visitors by Company​

4. Visitors Viewing Specific Pages​

5. Visitors by UTM Campaign​

6. Visitor Engagement Trend​

7. Visitors by Job Title​

8. Visitors by Device Type​

9. Visitors by Geographic Location​

10. High-Intent Visitors​

11. Session Analysis​

12. Repeat Visitors​

Best Practices​

1. Always Check Schema First​

2. Use Wildcard for Text Search​

3. Filter for Identified Visitors​

4. Include Key Fields in _source​

5. Use .keyword for Exact Matches​

6. Apply Date Filters​

7. Generate Clickable Links​

8. Combine Engagement Metrics​

Query Patterns​

Multiple Filters Combined​

Text Search Across Multiple Fields​

Aggregations for Insights​

Sorting by Multiple Fields​

Workflow Example​