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.

13.9 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 subscriptions
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product subscriptions
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Subscriptions
feature: subscriptions
url_prefix: /subscriptions
ui_apps: {}
tools:
    subscriptions-create:
        operation: subscriptions_create
        enabled: true
        scopes:
            - subscription:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Create subscription
        description: >
            Create a recurring subscription. The kind is inferred from which field you populate and returned as the
            read-only `resource_type`:

            (1) set `insight` — schedule periodic snapshots of one insight (`resource_type: "insight"`).

            (2) set `dashboard` and `dashboard_export_insights` (the subset of the dashboard's insights to include, max
            20) — schedule periodic snapshots of one dashboard (`resource_type: "dashboard"`).

            (3) set `prompt` (≤4000 chars, with no insight or dashboard) — schedule a recurring LLM-generated report
            (`resource_type: "ai_prompt"`). Available on PostHog Cloud (self-hosted production is not eligible) once the
            organization has approved AI data processing and prompt subscriptions are enabled for it; otherwise create
            is rejected with a 400. Creating a prompt subscription also requires the `query:read` scope — the report
            runs LLM-generated HogQL over your data — so a `subscription:write`-only token is rejected for this kind.

            Delivery is set by `target_type` — `email`, `slack`, or `teams` (a Microsoft Teams webhook URL in
            `target_value`). A Teams webhook URL is only ever read back as its host. Creating a Teams subscription
            requires the full webhook URL in `target_value`.

            Set `start_date` to an ISO 8601 datetime. Its date anchors the recurrence and may be in the past. Deliveries
            run on half-hour cycles at :00 and :30. Other minute values are accepted for backward compatibility, but
            delivery happens during the next cycle instead of at that exact minute. For example, use a value ending in
            `T16:30:00Z` for the 16:30 delivery cycle.

            The kind is fixed at create time — a PATCH that would change the populated relation to a different kind is
            rejected.

            For insight and dashboard subscriptions you can attach an AI-generated summary to each delivery by setting
            `summary_enabled: true` (optionally steered by `summary_prompt_guide`, which must be 500 characters or
            fewer). This requires the organization to have approved AI data processing and to be within its
            active-summary cap and AI credit budget; otherwise the create is rejected. Prompt subscriptions are
            themselves AI-generated, so these fields do not apply to them.

            `delivery_config` is optional, and every option in it applies to one subscription kind or delivery target
            only. Omit the whole field unless the user asks for one of its options, because the create is rejected when
            an option does not apply. Each option's own description says where it applies. None of them control the AI
            summary on an insight or dashboard subscription, so use `summary_enabled` and `summary_prompt_guide` for
            that instead.

            IMPORTANT — when creating an insight (or dashboard) subscription, always ask the user whether to enable the
            AI-generated summary before creating it. Present it as their choice: they can turn it on (`summary_enabled:
            true`) or leave it off, and if they turn it on, offer them the option to add a custom prompt to steer the
            summary (`summary_prompt_guide`). Do not enable the summary on your own without asking. (Prompt
            subscriptions are themselves AI-generated, so this does not apply to them.)
        exclude_params:
            - contexts
            - deleted
            - next_delivery_date
            - resource_name
            - insight_short_id
            - invite_message
    subscriptions-delete:
        operation: subscriptions_destroy
        enabled: true
        scopes:
            - subscription:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete subscription
        description: >
            Soft-delete a subscription. Stops all future deliveries and returns the subscription with `deleted: true`.
            One-way via MCP — there is no restore tool, so re-create the subscription if you need it back. Deleting an
            prompt subscription additionally requires the `query:read` scope (the backend gates every write touching a
            prompt subscription on query access).
        param_overrides:
            id:
                cast: string-int
        soft_delete: true
        response:
            exclude:
                - invite_message
    subscriptions-deliveries-list:
        operation: subscriptions_deliveries_list
        enabled: true
        scopes:
            - subscription:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List subscription deliveries
        description: >
            List delivery history for a subscription — one row per send attempt. Each entry includes status (starting,
            completed, failed, skipped), trigger_type (scheduled, manual, target_change), and timestamps (created_at,
            finished_at). Filter with status=failed to quickly surface failed deliveries. Results are cursor-paginated
            newest first. content_snapshot, recipient_results, and error are excluded to avoid leaking recipient
            identifiers or upstream response bodies that may contain tokens / PII. ai_report (the full report markdown),
            ai_report_prompt (the prompt it was generated from), and ai_report_diagnostics (per-query debug detail) are
            also excluded here to keep list responses small — fetch a single delivery with
            subscriptions-deliveries-retrieve to read the report and its prompt.
        response:
            exclude:
                - content_snapshot
                - recipient_results
                - error
                - ai_report
                - ai_report_prompt
                - ai_report_diagnostics
    subscriptions-deliveries-retrieve:
        operation: subscriptions_deliveries_retrieve
        enabled: true
        scopes:
            - subscription:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get subscription delivery
        description: >
            Fetch a single subscription delivery attempt by id. Returns status, trigger_type, target_type, target_value,
            timestamps, workflow/idempotency metadata, and exported_asset_ids. content_snapshot (the frozen
            dashboard/insight state at send time) is not returned — use the insight/dashboard tools for current state.
            recipient_results and error are also excluded to avoid leaking recipient identifiers or upstream response
            bodies that may contain tokens / PII. Unlike the list tool, ai_report (the full report markdown for
            AI-prompt subscriptions) is returned here, alongside ai_report_prompt (the prompt it was generated from).
            ai_report_diagnostics (per-query generated HogQL + failure types) is excluded to keep the response focused
            on the report itself.
        response:
            exclude:
                - content_snapshot
                - recipient_results
                - error
                - ai_report_diagnostics
    subscriptions-list:
        operation: subscriptions_list
        enabled: true
        scopes:
            - subscription:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{id}'
        list: true
        title: List subscriptions
        description: >
            List the team's subscriptions. Use `search` to filter by title, insight name (including the auto-generated
            name of an unnamed insight), dashboard name, or prompt text. Prompt subscriptions match both their `title`
            and `prompt` text.
        response:
            exclude:
                - invite_message
    subscriptions-partial-update:
        operation: subscriptions_partial_update
        enabled: true
        scopes:
            - subscription:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        title: Update subscription
        description: >
            Update a subscription's mutable fields (title, target, schedule, the `prompt` for prompt subscriptions,
            `enabled`). The kind (`resource_type`) is fixed at create — a PATCH that would introduce another kind's
            field (e.g. a `prompt` on an insight sub) is rejected with 400. For prompt subs, re-enabling a previously
            auto-disabled sub requires both a valid `prompt` (already persisted or supplied in the PATCH body) and that
            the original creator is still an active user; otherwise it is rejected with 400. Editing or re-enabling a
            prompt subscription additionally requires the `query:read` scope. Use `subscriptions-delete` to soft-delete
            — `deleted` is not settable here.

            For Microsoft Teams, omit `target_value` to keep the stored webhook URL. To replace it, send a full Teams
            webhook URL; the host returned by this API is not a valid replacement.

            For insight and dashboard subscriptions, toggle the per-delivery AI summary with `summary_enabled` and steer
            it with `summary_prompt_guide` (500 characters or fewer). Enabling a summary requires the organization to
            have approved AI data processing and to be within its active-summary cap and AI credit budget; otherwise the
            update is rejected.

            `delivery_config` options carry the same scope rules as on create, and the update is rejected when an option
            you send does not apply to this subscription. On a prompt subscription the object you send merges into the
            stored one instead of replacing it, so set an option to the value you want rather than expecting an omitted
            option to be cleared.
        exclude_params:
            - contexts
            - deleted
            - next_delivery_date
            - resource_name
            - insight_short_id
            - invite_message
            - send_test_now
    subscriptions-retrieve:
        operation: subscriptions_retrieve
        enabled: true
        scopes:
            - subscription:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get subscription
        description:
            'Fetch a single subscription by numeric ID. Returns its kind (`resource_type`: insight, dashboard, or
            ai_prompt), target (`target_type`/`target_value`, host-only for a Teams webhook), schedule, enabled state,
            and AI-summary settings. Metadata only — for the send history and delivered reports, use
            `subscriptions-deliveries-list` / `subscriptions-deliveries-retrieve`.'
        response:
            exclude:
                - invite_message
    subscriptions-summaries-list:
        operation: subscriptions_summaries_list
        enabled: true
        scopes:
            - subscription:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List AI summaries for an insight or dashboard
        description: >
            List the AI summaries that subscriptions sent for one insight or dashboard, newest first. Set exactly one of
            `insight` or `dashboard` (numeric ID). Each row comes from a completed delivery and includes the summary
            text, the subscription ID and title, the channel, and the covered period from `period_start` to
            `created_at`. `period_start` is null for the first delivery of a subscription. Summaries from deleted
            subscriptions are not returned. Use subscriptions-partial-update with `summary_prompt_guide` to change how
            future summaries of one subscription are written. Results are cursor-paginated.
        feature_flag: subscription-source-summaries
    subscriptions-test-delivery-create:
        operation: subscriptions_test_delivery_create
        enabled: true
        scopes:
            - subscription:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Send test delivery
        description: >
            Trigger an immediate test delivery of a subscription to its configured target(s) (email, Slack, or Microsoft
            Teams). Runs the same pipeline as a scheduled delivery but with trigger_type=manual, producing a real
            delivery record you can inspect via subscriptions-deliveries-list / subscriptions-deliveries-retrieve.
            Returns 202 Accepted once the delivery workflow is queued; poll subscriptions-deliveries-list (newest first)
            or subscriptions-deliveries-retrieve for the outcome. Returns 409 if a test delivery for the same
            subscription is already in flight, or if the subscription is disabled (re-enable it first); 404 if it has
            been deleted. Test-delivering a prompt subscription additionally requires the `query:read` scope (it runs
            the AI HogQL pipeline).