:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
# MCP tool definitions. Tools are opt-in: an operation is exposed only when it has an entry here.
# List operations without an entry: pnpm --filter=@posthog/mcp run scaffold-yaml -- --candidates --product web_analytics
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product web_analytics
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Web analytics
feature: web_analytics
url_prefix: /web
ui_apps: {}
tools:
heatmaps-events:
operation: heatmaps_events_retrieve
enabled: true
scopes:
- heatmap:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get sessions behind heatmap coordinates
description: >
Drill into the individual session interactions behind one or more heatmap coordinates. Pass `points` as a
JSON array of the spots you want to inspect (the `pointer_relative_x` / `pointer_y` values from
`heatmaps-list`), plus the same page/date filters. Returns the underlying per-session interactions so you
can open the session recordings that produced a hotspot.
heatmaps-list:
operation: heatmaps_list
enabled: true
scopes:
- heatmap:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List heatmap interactions for a page
description: >
Aggregated heatmap interactions captured on a page. Filter by `url_exact` (one page) or `url_pattern` (regex
across pages), a date window (`date_from`/`date_to`, data is retained 90 days), and optionally a viewport
range (`viewport_width_min`/`viewport_width_max`, CSS px) to isolate a device class. Set `type` to 'click'
(default), 'rageclick', 'mousemove', or 'scrolldepth'. For clicks each result is a point —
`pointer_relative_x` (0..1 across the viewport), `pointer_y` (absolute pixels down the page), and a `count`;
'scrolldepth' returns reach buckets instead. For the click types the response also includes a `fold` summary
— `pct_below_fold` (share of non-fixed interactions that landed below the user's initial viewport, i.e.
required scrolling), `below_fold_count`, `total_count`, and the `median_viewport_height` (the typical fold
line in CSS px) — so a high `pct_below_fold` flags engaged content sitting off the first screen. `rageclick`
hotspots and shallow scroll depth are the strongest signals that something on the page is confusing or
buried. Heatmaps only know coordinates, not what was clicked — cross-reference autocapture events on the
same URL to name the elements, and use `heatmaps-events` to jump to the sessions behind a hotspot. Click
results are returned hottest-first and capped at `limit` (default 500); busy pages have thousands of
distinct coordinates, so the default page plus the `fold` summary is usually enough for analysis — raise
`limit` or page with `offset` only if you need more, and check `has_more` to know when the list is
truncated.
heatmaps-saved-create:
operation: saved_create
enabled: true
scopes:
- heatmap:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Create a saved heatmap
description: >
Create a saved heatmap for a page URL. For type 'screenshot' (the default) this enqueues a headless render
of the page at each target width — poll `heatmaps-saved-get` until `status` is 'completed'; the rendered
page (with data overlaid) is then viewable by the user in the PostHog UI. Provide `widths` (CSS px,
100-3000) to control which viewports are rendered, or omit it for sensible defaults. The URL must be exact —
wildcards are not allowed.
exclude_params:
- deleted
heatmaps-saved-get:
operation: saved_retrieve
enabled: true
scopes:
- heatmap:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get a saved heatmap
description: >
Get a single saved heatmap by its `short_id`, including per-width render `status`. Poll this after
`heatmaps-saved-create` until `status` is 'completed'; the rendered page is then viewable by the user in the
PostHog UI.
heatmaps-saved-list:
operation: saved_list
enabled: true
scopes:
- heatmap:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List saved heatmaps
description: >
List saved heatmaps for the project. A saved heatmap pins a page URL plus a set of viewport widths and (for
type 'screenshot') renders the page so heatmap data can be overlaid on it. Filter by `type`, `status`,
`created_by`, or a `search` substring on URL/name. The rendered page (screenshot with data overlaid) is
viewable by the user in the PostHog UI.
heatmaps-saved-regenerate:
operation: saved_regenerate_create
enabled: true
scopes:
- heatmap:write
annotations:
readOnly: false
destructive: true
idempotent: false
title: Regenerate a saved heatmap screenshot
description: >
Re-run screenshot generation for a saved heatmap of type 'screenshot' by its `short_id`. Clears the existing
renders and re-renders at every target width; `status` returns to 'processing'. Use when a page has changed
or a render failed.
heatmaps-saved-update:
operation: saved_partial_update
enabled: true
scopes:
- heatmap:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Update a saved heatmap
description: >
Update a saved heatmap by its `short_id`. Send only the fields to change — rename via `name`, change
`widths`, or soft-delete by setting `deleted: true` (deletion goes through this update, not a destroy call).
Changing the `url` of a 'screenshot' heatmap triggers a fresh render.
web-analytics-bot-rules-create:
operation: web_analytics_bot_rules_create
enabled: true
scopes:
- web_analytics:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Create a custom bot rule
description: >
Add one bot rule so traffic matching it classifies as a bot. A rule holds one or more conditions in `items`,
combined with `combiner` ('AND' or 'OR', default 'AND'). Each condition sets `key` to the event property to
read (such as $raw_user_agent, $screen_width, or $ip), `matcher` to 'contains' (case-insensitive substring),
'regex' (RE2), 'exact' (case-sensitive equality), or 'cidr' (an IP network range, only with $ip), and
`pattern` to the value to match. Set `name` to the label to report, and optionally `category` to a built-in
category like ai_crawler to relabel the traffic type. The rule is rejected if a pattern cannot run. Use this
when a scraper is hitting the site that the built-in list misses, including one only identifiable by a
combination of properties (an 800x600 screen).
web-analytics-bot-rules-destroy:
operation: web_analytics_bot_rules_destroy
enabled: true
scopes:
- web_analytics:write
annotations:
readOnly: false
destructive: true
idempotent: false
title: Delete a custom bot rule
description: |
Delete one bot rule by its `id` (from the list tool). The built-in bot list is unaffected.
web-analytics-bot-rules-list:
operation: web_analytics_bot_rules_list
enabled: true
scopes:
- web_analytics:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List custom bot rules
description: >
List the project's own bot rules. Each rule names an event property, how to match it, a value, and the label
reported when it matches. Rules extend PostHog's built-in bot list, so `Is bot` (isLikelyBot), `Bot name`,
and `Traffic category` reflect them everywhere — insights, web analytics, session filters, and SQL.
web-analytics-path-cleaning-suggestions-apply:
operation: web_analytics_path_cleaning_suggestions_apply
enabled: true
scopes:
- web_analytics:write
annotations:
readOnly: false
destructive: true
idempotent: false
title: Apply a path-cleaning suggestion
description: >
Apply a suggested set of path-cleaning rules by its health-issue `id`, merging them into the project's path
cleaning configuration. Existing rules are never overwritten — only new rules are appended — and the
underlying `path_cleaning_suggestions` health issue is resolved. Returns how many rules were added. Requires
project admin (the same gate as editing path cleaning rules in team settings). Applying changes historical
numbers in every Web analytics and Paths chart that has cleaning enabled, so confirm with the user before
calling this.
feature_flag: web-analytics-path-cleaning-suggestions
web-analytics-path-cleaning-suggestions-generate:
operation: web_analytics_path_cleaning_suggestions_generate
enabled: true
scopes:
- web_analytics:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Generate path-cleaning suggestions
description: >
Analyze the project's recent URL paths and generate suggested path-cleaning rules on demand. Samples the
most-viewed paths, asks the model for `{regex, alias}` rules, and validates each against the real paths
(dropping any that don't match), then stores the result as a `path_cleaning_suggestions` health issue.
Returns `status` ('generated' with a `suggestion`, or a skip reason like 'skipped_no_paths' /
'skipped_low_cardinality' when there isn't enough to suggest from). Pending suggestions surface through the
health-issues API (filter `kind=path_cleaning_suggestions`); dismiss one by PATCHing the issue's `dismissed`
flag. Use when the user asks to clean up or normalize their paths and no suggestion exists yet. This only
proposes rules — apply them with `web-analytics-path-cleaning-suggestions-apply`; nothing changes until
then.
requires_ai_consent: true
feature_flag: web-analytics-path-cleaning-suggestions
web-analytics-weekly-digest:
operation: web_analytics_weekly_digest
enabled: true
scopes:
- web_analytics:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Summarize web analytics
description: >
Summarizes a project's web analytics over a lookback window (default 7 days): unique visitors, pageviews,
sessions, bounce rate, and average session duration with period-over-period comparisons, plus the top 5
pages, top 5 traffic sources, and goal conversions. Accepts optional `days` (1–90, default 7) and `compare`
(bool, default true) query params — pass `days=30` to summarize the last month, or `compare=false` to skip
the period-over-period comparison for a faster response. Use this to answer questions like "how are my web
analytics?", "how did the site do last week?", or "what's my traffic looking like this month?".
wrappers:
query-web-overview:
schema_ref: AssistantWebOverviewQuery
enabled: true
scopes:
- query:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Run a web analytics overview query
description_file: ./prompts/query-web-overview.md
system_prompt_hint: Web analytics KPIs — visitors, sessions, bounce rate, session duration
ui_resource_uri: ui://posthog/query-results.html
exclude_properties:
- response
- modifiers
- samplingFactor
use_optimized_output: false
query-web-stats:
schema_ref: AssistantWebStatsTableQuery
enabled: true
scopes:
- query:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Run a web analytics breakdown table query
description_file: ./prompts/query-web-stats.md
system_prompt_hint: Web analytics breakdowns — top pages, UTMs, devices, countries, with bounce rate
ui_resource_uri: ui://posthog/query-results.html
exclude_properties:
- response
- modifiers
- samplingFactor
use_optimized_output: false
query-web-vitals:
schema_ref: AssistantWebVitalsPathBreakdownQuery
enabled: true
scopes:
- query:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Run a web vitals path breakdown query
description_file: ./prompts/query-web-vitals.md
system_prompt_hint: Core Web Vitals per page — LCP, INP, CLS, FCP bucketed into good / needs-improvement / poor
ui_resource_uri: ui://posthog/query-results.html
exclude_properties:
- response
- modifiers
- samplingFactor
use_optimized_output: false