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.

5.6 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 annotations
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product annotations
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Annotations
feature: annotations
url_prefix: /data-management/annotations
ui_apps: {}
tools:
    annotation-create:
        operation: annotations_create
        enabled: true
        scopes:
            - annotation:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        title: Create annotation
        description: >
            Create an annotation to mark an important change (for example, a deployment) on charts and trends. Provide a
            note in `content`, when it happened in `date_marker` (ISO 8601), and its `scope`: the current `project`, the
            whole `organization`, one insight, or one dashboard. To annotate one insight, set `scope` to
            `dashboard_item` and `dashboard_item` to the insight's numeric ID. To annotate one dashboard, set `scope` to
            `dashboard` and `dashboard_id` to the dashboard ID. Optionally set an `emoji` to show in place of the
            default badge on the chart.
        include_params:
            - content
            - date_marker
            - scope
            - dashboard_item
            - dashboard_id
            - emoji
            - hidden_in_user_interface
    annotation-delete:
        operation: annotations_destroy
        enabled: true
        scopes:
            - annotation:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete annotation
        description: >
            Soft-delete an annotation by ID. This hides the annotation from normal lists while preserving historical
            records.
        soft_delete: true
    annotation-retrieve:
        operation: annotations_retrieve
        enabled: true
        scopes:
            - annotation:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Retrieve annotation
        description: >
            Retrieve a single annotation by ID from the current project. Use this when you already know the annotation
            ID and want complete details.
        param_overrides:
            id:
                cast: string-int
    annotations-list:
        operation: annotations_list
        enabled: true
        scopes:
            - annotation:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: List annotations
        description: >
            List annotations in the current project, newest first. Use this to review existing deployment markers and
            analysis notes before adding new annotations. Results are paginated (default 100 per page) — use `limit` and
            `offset` to page through, and `search` to filter by annotation content. Each row's `created_by` is trimmed
            to `{id, email}`.
        param_overrides:
            limit:
                description: Number of annotations to return per page (default 100).
                default: 100
        response:
            exclude:
                - created_by.uuid
                - created_by.distinct_id
                - created_by.first_name
                - created_by.last_name
                - created_by.is_email_verified
                - created_by.hedgehog_config
                - created_by.role_at_organization
    annotations-partial-update:
        operation: annotations_partial_update
        enabled: true
        scopes:
            - annotation:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        title: Update annotation
        description: >
            Update an existing annotation by ID. You can change its text (`content`), when it happened (`date_marker`,
            ISO 8601), its visibility scope, or its `emoji`. To scope it to one insight, set `scope` to `dashboard_item`
            and `dashboard_item` to the insight's numeric ID. To scope it to one dashboard, set `scope` to `dashboard`
            and `dashboard_id` to the dashboard ID. Only the fields you provide are updated.
        include_params:
            - content
            - date_marker
            - scope
            - dashboard_item
            - dashboard_id
            - emoji
            - hidden_in_user_interface
    change-feed-list:
        operation: change_feed_list
        enabled: true
        scopes:
            - annotation:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: List recent production changes
        description: >
            List the changes that can affect production in a time window, newest first: feature flag and experiment
            edits, error tracking releases, and annotations. Use this first when you investigate an error spike, a
            latency regression, or a metric drop, to find what changed just before it. Set `date_from` and `date_to`
            (ISO 8601) around the incident. The default is the last 24 hours. Deploy annotations and releases can fill
            the page, so set `kinds` to `["feature_flag", "experiment"]` to see only configuration edits. When
            `has_more` is true, narrow the window or set `kinds`. Changes the user has no access to are left out.