Skip to content

: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.

14.2 KB
Raw Blame
# 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