MCP tools and inputs

Mrkr exposes 25 focused tools. Your assistant discovers only the tools allowed by its approved permissions. Read tools return recorded data; the two configuration tools update metadata and settings without creating traffic or purchases.

#Find a site first

Call mrkr_list_sites and use a returned id as site_id. Every other tool requires it. There is no active-site, public-demo or cross-workspace fallback.

#Tools

#Analytics inputs

{
  "site_id": "SITE_ID_FROM_LIST",
  "range": {
    "start": "2026-09-01",
    "end": "2026-09-30",
    "timezone": "Europe/Zurich"
  },
  "currency": "USD",
  "filters": {
    "device": [
      "desktop",
      "mobile"
    ],
    "event": [
      "signup_completed",
      "order_completed"
    ]
  },
  "sort": "revenue",
  "limit": 25,
  "offset": 0
}

range

Inclusive calendar dates start/end in YYYY-MM-DD form, spanning 1–366 days. timezone is a valid IANA timezone and defaults to UTC. Returned notes explain daily or epoch-bucket alignment.

filters

Arrays of values, OR within a dimension and AND across dimensions, up to 20 values each. Supported dimensions: country, region, city, device, browser, os, source, medium, utm_source, utm_medium, utm_campaign, entry_path, exit_path, referrer, language, timezone and event. Event filters select sessions with matching custom or conversion events in the range.

currency

One uppercase three-letter currency, or unknown. Omit to use the ledger's default; inspect available_currencies. Amounts are major currency units, never cents. Different currencies are never converted or added together.

limit / offset

Where supported: limit 1–100, default 25; offset 0–1000, default 0. Follow next_offset when present and respect source_truncated/upstream_cap. Aggregate rankings are not exhaustive exports.

For mrkr_traffic_revenue_buckets, bucket_seconds is a string: 900, 3600, 14400 or 86400. At most 744 buckets are returned; narrow the range or choose a larger interval. mrkr_visitors accepts segment all, converted or returning. The live tools do not take a date range. AI crawler totals take site_id and range only; session filters do not apply.

#Configure a custom event

Read mrkr_get_event_config first. With events:write, mrkr_configure_event can declare an event before its first occurrence or update an existing definition. Instrumentation still sends the actual event separately.

{
  "site_id": "SITE_ID_FROM_LIST",
  "event_name": "order_completed",
  "configuration": {
    "description": "Order completed",
    "is_conversion": true,
    "revenue_prop": "total"
  }
}

Allowed configuration fields: is_conversion, description, target_value, revenue_prop, verified and hidden. Omitted fields retain their values; null clears description, target_value or revenue_prop. description is a display label up to 280 characters. target_value is a nonnegative finite number. revenue_prop names a numeric captured property and requires is_conversion enabled. Keep browser event names within 64 characters.

window.mrkr?.track("order_completed", {
  total: 49.00,
  currency: "USD",
  plan: "pro"
});

#Change approved settings

{
  "site_id": "SITE_ID_FROM_LIST",
  "settings": {
    "name": "Marketing site",
    "replay_enabled": true,
    "replay_sample_rate": 0.25,
    "excluded_paths": [
      "/admin/*",
      "/preview-*"
    ]
  }
}

Allowed settings: name, tracking_mode (cookieless or cookie), replay_enabled, replay_sample_rate (0–1), and excluded_paths (up to 50 full-path glob patterns). Omitted fields stay unchanged; null or an empty array clears path exclusions. Switching cookie mode also requires the matching script attribute and your site's consent handling; see Cookie mode. MCP cannot change billing, team permissions, sharing credentials, proxy provisioning or delete sites.

#Read results accurately

• Revenue uses the source of the session that recorded it. Missing session attribution stays Unattributed. Refunds can reduce money totals; only positive recorded revenue counts as a purchase.
• Visitor purchase delay uses retained same-site history, not account age. mrkr_visitor_journey's purchase timing uses positive revenue events; a nonmonetary custom conversion does not imply a payment.
• Distinct visitors may repeat across time buckets. Never add bucket distinct counts and call the result total unique visitors.
• AI assistant traffic counts referred humans. AI crawlers count bot requests on UTC days. Keep these separate.
• Live totals cover five minutes of activity; visitor pins are bounded and may lack precise coordinates. Historical reads can be briefly cached; tool descriptions and freshness notes state their coverage.
• Top pages are capped at 20, journeys at the top 12 paths with sampling flags, and performance at the latest 10,000 samples and 20 pages. Missing measurements remain null. Web Vitals use milliseconds except unitless CLS; overview durations use seconds and conversion rates are fractions.
• Event property counters use site-wide UTC-day rollups. Event totals, trends, samples and destinations honor session filters; property counters do not. Property samples are sanitized and bounded, but may contain values your instrumentation supplied.

#Limits and errors

Each connection allows 120 authenticated HTTP requests per minute. Honor Retry-After on a 429. Expired or invalid credentials return 401; denied sites, missing scopes or revoked consent return 403. Reconnect for renewed consent instead of retrying an unauthorized request. Send one JSON-RPC message per POST; batch arrays are rejected and request bodies are capped at 65,536 UTF-8 bytes. Tool-level failures return isError with a readable message. Inputs reject unknown fields; responses are capped at 200,000 bytes, so narrow ranges, filters or pages for oversized results.

Successful configuration writes return changed_fields and invalidate affected analytics caches. The audit records the tool, site, actor and changed field names; it does not store OAuth bearer tokens or configuration payload values.