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