posthog-automation

PostHog Automation via Rube MCP

Automate PostHog product analytics and feature flag management through Composio's PostHog toolkit via Rube MCP.

Prerequisites

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)

Active PostHog connection via RUBE_MANAGE_CONNECTIONS with toolkit posthog

Always call RUBE_SEARCH_TOOLS first to get current tool schemas

Setup

Get Rube MCP: Add https://rube.app/mcp as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming RUBE_SEARCH_TOOLS responds

Call RUBE_MANAGE_CONNECTIONS with toolkit posthog

If connection is not ACTIVE, follow the returned auth link to complete PostHog authentication

Confirm connection status shows ACTIVE before running any workflows

Core Workflows

1. Capture Events

When to use: User wants to send event data to PostHog for analytics tracking

Tool sequence:

POSTHOG_CAPTURE_EVENT - Send one or more events to PostHog [Required]

Key parameters:

event: Event name (e.g., '$pageview', 'user_signed_up', 'purchase_completed')

distinct_id: Unique user identifier (required)

properties: Object with event-specific properties

timestamp: ISO 8601 timestamp (optional; defaults to server time)

Pitfalls:

distinct_id is required for every event; identifies the user/device

PostHog system events use $ prefix (e.g., '$pageview', '$identify')

Custom events should NOT use the $ prefix

Properties are freeform; maintain consistent schemas across events

Events are processed asynchronously; ingestion delay is typically seconds

2. List and Filter Events

When to use: User wants to browse or search through captured events

Tool sequence:

POSTHOG_LIST_AND_FILTER_PROJECT_EVENTS - Query events with filters [Required]

Key parameters:

project_id: PostHog project ID (required)

event: Filter by event name

person_id: Filter by person ID

after: Events after this ISO 8601 timestamp

before: Events before this ISO 8601 timestamp

limit: Maximum events to return

offset: Pagination offset

Pitfalls:

project_id is required; resolve via LIST_PROJECTS first

Date filters use ISO 8601 format (e.g., '2024-01-15T00:00:00Z')

Large event volumes require pagination; use offset and limit

Results are returned in reverse chronological order by default

Event properties are nested; parse carefully

3. Manage Feature Flags

When to use: User wants to create, view, or manage feature flags

Tool sequence:

POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS - List existing feature flags [Required]

POSTHOG_RETRIEVE_FEATURE_FLAG_DETAILS - Get detailed flag configuration [Optional]

POSTHOG_CREATE_FEATURE_FLAGS_FOR_PROJECT - Create a new feature flag [Optional]

Key parameters:

For listing: project_id (required)

For details: project_id, id (feature flag ID)

For creation:

- project_id: Target project
- key: Flag key (e.g., 'new-dashboard-beta')
- name: Human-readable name
- filters: Targeting rules and rollout percentage
- active: Whether the flag is enabled

Pitfalls:

Feature flag key must be unique within a project

Flag keys should use kebab-case (e.g., 'my-feature-flag')

filters define targeting groups with properties and rollout percentages

Creating a flag with active: true immediately enables it for matching users

Flag changes take effect within seconds due to PostHog's polling mechanism

4. Manage Projects

When to use: User wants to list or inspect PostHog projects and organizations

Tool sequence:

POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION - List all projects [Required]

Key parameters:

organization_id: Organization identifier (may be optional depending on auth)

limit: Number of results per page

offset: Pagination offset

Pitfalls:

Project IDs are numeric; used as parameters in most other endpoints

Organization ID may be required; check your PostHog setup

Pagination is offset-based; iterate until results are empty

Project settings include API keys and configuration details

5. User Profile and Authentication

When to use: User wants to check current user details or verify API access

Tool sequence:

POSTHOG_WHOAMI - Get current API user information [Optional]

POSTHOG_RETRIEVE_CURRENT_USER_PROFILE - Get detailed user profile [Optional]

Key parameters:

No required parameters for either call

Returns current authenticated user's details, permissions, and organization info

Pitfalls:

WHOAMI is a lightweight check; use for verifying API connectivity

User profile includes organization membership and permissions

These endpoints confirm the API key's access level and scope

Common Patterns

ID Resolution

Organization -> Project ID:

1. Call POSTHOG_LIST_PROJECTS_IN_ORGANIZATION_WITH_PAGINATION
Find project by name in results

Extract id (numeric) for use in other endpoints

Feature flag name -> Flag ID:

1. Call POSTHOG_LIST_AND_MANAGE_PROJECT_FEATURE_FLAGS with project_id
Find flag by key or name

Extract id for detailed operations

Feature Flag Targeting

Feature flags support sophisticated targeting:

{
  "filters": {
    "groups": [
      {
        "properties": [
          {"key": "email", "value": "@company.com", "operator": "icontains"}
        ],
        "rollout_percentage": 100
      },
      {
        "properties": [],
        "rollout_percentage": 10
      }
    ]
  }
}

Groups are evaluated in order; first matching group determines the rollout

Properties filter users by their traits

Rollout percentage determines what fraction of matching users see the flag

Pagination

Events: Use offset and limit (offset-based)

Feature flags: Use offset and limit (offset-based)

Projects: Use offset and limit (offset-based)

Continue until results array is empty or smaller than limit

Known Pitfalls

Project IDs:

Required for most API endpoints

Always resolve project names to numeric IDs first

Multiple projects can exist in one organization

Event Naming:

System events use $ prefix ($pageview, $identify, $autocapture)

Custom events should NOT use $ prefix

Event names are case-sensitive; maintain consistency

Feature Flags:

Flag keys must be unique within a project

Use kebab-case for flag keys

Changes propagate within seconds

Deleting a flag is permanent; consider disabling instead

Rate Limits:

Event ingestion has throughput limits

Batch events where possible for efficiency

API endpoints have per-minute rate limits

Response Parsing:

Response data may be nested under data or results key

Paginated responses include count, next, previous fields

Event properties are nested objects; access carefully

Parse defensively with fallbacks for optional fields

Quick Reference