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.

8.7 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 endpoints
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product endpoints
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Endpoints
feature: endpoints
url_prefix: /endpoints
ui_apps: {}
tools:
    endpoint-create:
        operation: endpoints_create
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: false
        enrich_url: '{name}'
        title: Create endpoint
        description: >
            Create a new API endpoint from a HogQL or insight query. The name must be URL-safe (letters, numbers,
            hyphens, underscores, starts with a letter, max 128 chars). Set is_materialized to true to materialize an
            eligible query.
        include_params:
            - name
            - query
            - description
            - is_materialized
            - data_freshness_seconds
            - tags
    endpoint-delete:
        operation: endpoints_destroy
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: true
            idempotent: true
        title: Delete endpoint
        description: |
            Delete an endpoint by name. The endpoint is soft-deleted and its materialized views are cleaned up.
        soft_delete: true
    endpoint-get:
        operation: endpoints_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Get endpoint
        description: >
            Get a specific endpoint by name. Returns the full endpoint configuration including query definition, version
            info, materialization status, and column types. Supports ?version=N to retrieve a specific version.
    endpoint-logs:
        operation: endpoints_logs_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        list: true
        title: Get endpoint logs
        description: >
            Retrieve execution logs for an endpoint by name. Each run emits one entry with a timestamp, level (INFO or
            ERROR), and a message whose extra data is in key=value tokens (path=materialized|inline|ducklake,
            cache=hit|miss, duration_ms=, rows=, version=, error=). Filter by level (e.g. "ERROR"), text search (e.g.
            "cache=miss"), time range (after/before), a specific execution (instance_id), and limit (max 500). Use to
            debug why an endpoint failed, timed out, missed cache, or returned unexpected row counts.
    endpoint-materialization-status:
        operation: endpoints_materialization_status_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Get materialization status
        description: >
            Get lightweight materialization status for an endpoint without fetching full endpoint data. Returns whether
            materialization is possible, current status, last run time, and any errors. Supports ?version=N.
    endpoint-openapi-spec:
        operation: endpoints_openapi_spec_retrieve
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get endpoint OpenAPI spec
        description: >
            Get the OpenAPI 3.0 specification for an endpoint. Returns a JSON spec that can be used with SDK generators
            like openapi-generator or @hey-api/openapi-ts to create typed API clients. Supports ?version=N to generate a
            spec for a specific version.
    endpoint-run:
        operation: endpoints_run_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Run endpoint
        description: >
            Execute an endpoint's query and return results. Uses materialized results when available, otherwise runs
            inline. For HogQL endpoints, variable keys must match code_name values. For insight endpoints with
            breakdowns, use the breakdown property name as the key.
        include_params:
            - variables
            - limit
            - offset
            - refresh
        param_overrides:
            variables:
                description: >
                    Key-value pairs to parameterize the query. For HogQL endpoints, keys match variable code_name (e.g.
                    {"event_name": "$pageview"}). For insight endpoints with breakdowns, use the breakdown property name
                    as key.
    endpoint-update:
        operation: endpoints_partial_update
        enabled: true
        scopes:
            - endpoint:write
        annotations:
            readOnly: false
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        title: Update endpoint
        description: >
            Update an existing endpoint by name. Can update the query (auto-creates a new version), description, data
            freshness, active status, and materialization. Pass version in body to target a specific version for
            non-query updates.
        include_params:
            - query
            - description
            - is_active
            - is_materialized
            - data_freshness_seconds
            - version
            - tags
    endpoint-versions:
        operation: endpoints_versions_list
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        list: true
        title: Get endpoint versions
        description: >
            List all versions for an endpoint, in descending order (latest first). Each version contains the query
            snapshot, description, data freshness, last execution time, and materialization status at that point in
            time.
    endpoints-get-all:
        operation: endpoints_list
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{name}'
        list: true
        title: Get all endpoints
        description: >
            Get all API endpoints in the current project. Endpoints expose saved HogQL or insight queries as callable
            API routes. Returns name, description, query, active status, current version, and materialization info for
            each endpoint.
    endpoints-last-execution-times:
        operation: endpoints_last_execution_times_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        title: Get endpoints last execution times
        description: >
            Get the most recent execution time per endpoint (endpoint-level, personal API key calls only). Pass an array
            of endpoint names; returns rows shaped [name, last_executed_at]. Endpoints never called are omitted from the
            response. Use this for a quick endpoint-level recency check during an audit; for per-version usage or
            history, query the query_log table with execute-sql.
        include_params:
            - names
    endpoints-materialization-preview:
        operation: endpoints_materialization_preview_create
        enabled: true
        scopes:
            - endpoint:read
        annotations:
            readOnly: true
            destructive: false
            idempotent: true
        enrich_url: '{params.name}'
        title: Preview endpoint materialization
        description: >
            Preview the materialization transform for an endpoint before enabling it. Returns the transformed HogQL,
            detected range pairs, and aggregate re-aggregation info, plus a rejection reason if the query is not
            eligible. Supports an optional version body param. Read-only — does not enable materialization.
        include_params:
            - version
            - bucket_overrides