PostHog (MCP)

Connect PostHog’s hosted MCP server so OpenSRE can query analytics, feature flags, error tracking, and HogQL during investigations

Overview

OpenSRE connects to PostHog’s hosted Model Context Protocol (MCP) server. During investigations the agent can call PostHog products — product analytics, feature flags, error tracking, experiments, surveys, and HogQL — through MCP tools.

This is separate from the PostHog REST integration, which only stores project credentials for the REST API. The onboarding wizard lists PostHog (REST) and PostHog (MCP) as separate choices. Configure REST with opensre integrations setup posthog.

Prerequisites

• A PostHog account (US or EU — the hosted server routes you automatically)
• A PostHog personal API key created with the MCP Server preset. See PostHog personal API keys.

OpenSRE defaults to read-only access (x-posthog-read-only: true) so investigations cannot mutate your PostHog project. Set POSTHOG_MCP_READ_ONLY=false only if you explicitly want the agent to perform writes.

Setup

Option 1: Interactive CLI

opensre integrations setup posthog_mcp
opensre integrations verify posthog_mcp

Or run opensre integrations setup and select PostHog (MCP). Paste your personal API key. Setup uses the hosted Streamable HTTP transport; keep the default URL unless you have a reason to change it. For a local server, set POSTHOG_MCP_MODE=stdio (see below).

Option 2: Environment variables

POSTHOG_MCP_MODE=streamable-http
POSTHOG_MCP_URL=https://mcp.posthog.com/mcp
POSTHOG_MCP_AUTH_TOKEN=phx_your_personal_api_key
POSTHOG_MCP_PROJECT_ID=12345          # optional, scope to one project
POSTHOG_MCP_ORGANIZATION_ID=          # optional, scope to one organization
POSTHOG_MCP_FEATURES=                 # optional, comma-separated feature filter
POSTHOG_MCP_READ_ONLY=true            # optional, default true

Variable	Default	Description
POSTHOG_MCP_AUTH_TOKEN	—	Required (hosted). Personal API key with the MCP Server preset
POSTHOG_MCP_URL	https://mcp.posthog.com/mcp	MCP server URL (use https://mcp-eu.posthog.com/mcp to pin EU)
POSTHOG_MCP_MODE	streamable-http	Transport: streamable-http, sse, or stdio
POSTHOG_MCP_PROJECT_ID	—	Scope tools to a specific PostHog project
POSTHOG_MCP_ORGANIZATION_ID	—	Scope tools to a specific organization
POSTHOG_MCP_FEATURES	—	Comma-separated feature filter (e.g. flags,error-tracking)
POSTHOG_MCP_READ_ONLY	true	Send the read-only header so the agent cannot mutate PostHog
POSTHOG_MCP_COMMAND	—	Command to launch a local MCP server (stdio mode only)
POSTHOG_MCP_ARGS	—	Arguments for the local MCP command (stdio mode only)

Local PostHog MCP server via stdio:

POSTHOG_MCP_MODE=stdio
POSTHOG_MCP_COMMAND=npx
POSTHOG_MCP_ARGS=-y @posthog/mcp-server@latest
POSTHOG_MCP_AUTH_TOKEN=phx_your_personal_api_key

Option 3: Persistent store

{
  "version": 1,
  "integrations": [
    {
      "id": "posthog-mcp-prod",
      "service": "posthog_mcp",
      "status": "active",
      "credentials": {
        "url": "https://mcp.posthog.com/mcp",
        "mode": "streamable-http",
        "auth_token": "phx_your_personal_api_key",
        "project_id": "12345",
        "read_only": true
      }
    }
  ]
}

Credentials

Use a PostHog personal API key created with the MCP Server preset. See PostHog personal API keys.

Set it as POSTHOG_MCP_AUTH_TOKEN (or paste it during interactive setup). Optionally scope with POSTHOG_MCP_PROJECT_ID and POSTHOG_MCP_ORGANIZATION_ID.

Investigation tools

Tool	What it does
list_posthog_tools	List tools the connected PostHog MCP server exposes (compact, filterable)
call_posthog_tool	Call a named PostHog MCP tool (for example run a HogQL query, list feature flags, inspect an error)

Typical flow: call list_posthog_tools first, then call_posthog_tool with the chosen name and arguments.

The hosted PostHog MCP server exposes a large vendor catalog of tools (often 240+), each with a full input schema. Returning all of them at once exceeds most model context windows, so list_posthog_tools returns a compact, bounded listing — names plus short descriptions, without schemas.

Tip	Detail
Narrow the list	Pass name_filter (space- or comma-separated terms, e.g. "events query sql")
Fetch schemas	Pass include_schema=true on a narrowed list for the tool you intend to call
Query events	Use call_posthog_tool with tool_name="execute-sql" and a HogQL query (e.g. SELECT event, count() FROM events WHERE ... GROUP BY event). There is no search_events tool.

Verify

opensre integrations verify posthog_mcp

A successful check connects to the MCP server and reports how many tools it discovered.

Troubleshooting

Symptom	Fix
Missing or invalid personal API key	Use a key created with the MCP Server preset
Blocked outbound HTTPS	Confirm reachability to mcp.posthog.com (or mcp-eu.posthog.com if pinned to EU)

Security

OpenSRE defaults to read-only access (x-posthog-read-only: true) so investigations cannot mutate your PostHog project. Set POSTHOG_MCP_READ_ONLY=false only if you explicitly want the agent to perform writes. A successful check connects to the MCP server and reports how many tools it discovered. If it fails, the most common cause is a missing or invalid personal API key — confirm the key was created with the MCP Server preset and that outbound HTTPS to mcp.posthog.com is allowed.

Metric report (scheduled)

Deliver a per-metric PostHog analytics pulse to Telegram, Slack, or Rocket.Chat, on demand or on a schedule — coworker-style digests (what moved and why it matters), not a raw dashboard dump. Slack delivery needs a bot token (a webhook alone cannot honor --chat-id). This uses the headless posthog-summary skill path (schema discovery, then one bounded HogQL query per metric), not the investigation pipeline or generic opensre cron kinds. It requires the PostHog MCP integration above — the REST posthog integration alone cannot serve it.

Command	What it does
opensre posthog report run	Run once and print the per-metric report to stdout
opensre posthog report run --period 30d --metrics "active users,pageviews"	Run once for a custom window and metric focus
opensre posthog report schedule add	Schedule recurring delivery (cron + provider + chat)
opensre posthog report schedule list	List PostHog report schedules
opensre posthog report schedule run TASK_ID	Run a scheduled report immediately
opensre posthog report schedule remove TASK_ID	Remove a schedule

Example — every Monday at 08:00 London time to Telegram:

opensre posthog report schedule add \
  --cron "0 8 * * 1" \
  --tz Europe/London \
  --provider telegram \
  --chat-id "-1001234567890" \
  --period 7d

Example — same schedule to a Slack channel (C… member/channel id):

opensre posthog report schedule add \
  --cron "0 8 * * 1" \
  --tz Europe/London \
  --provider slack \
  --chat-id C0123ABCD \
  --period 7d

Slack delivery needs SLACK_BOT_TOKEN. A SLACK_WEBHOOK_URL alone will not work here: a webhook always posts to the one channel it was created for, so it cannot honour --chat-id.

--period accepts a relative window (24h, 7d, 30d; default 7d). Optional --metrics narrows the report to a comma-separated set instead of the default metric set.

The gateway daemon picks up scheduled reports automatically when it is running. If the LLM is unavailable, the run fails with an error (no deterministic fallback).

The report compares the current window against the previous comparable window per metric. Real zeros are reported as zeros; failed queries are called out as failures — never silently widened or fabricated, and never presented as zero when the query did not run.