/debugging-mcp-analytics

name: debugging-mcp-analytics
description: >
  Debug, support, and build PostHog MCP Analytics — product analytics for MCP
  servers (the `@posthog/mcp` and `posthog.mcp` SDKs plus the mcp_analytics
  product). Use when MCP analytics data looks wrong or missing ("events aren't
  showing", "intent clusters are empty", "sessions are missing", "per-tool
  numbers look wrong"), when writing queries over `$mcp_*` events by hand, or
  when doing feature work on the SDKs, the dashboard and its query runners, the
  self-instrumented MCP server, the `wizard mcp-analytics` install command, or
  the in-app onboarding. Covers the repo map, the `$mcp_*` vocabulary and where
  each property comes from, the rules that silently corrupt metrics when
  ignored, the end-to-end pipeline and where each stage breaks, and which repo
  to change. For reading the data rather than fixing it, prefer the
  `exploring-mcp-*` and `improving-mcp-tools` skills.

Debugging MCP analytics

**Product analytics for MCP servers.** A team ships an MCP server; the `@posthog/mcp` SDK wraps it in one line; every tool call, agent **intent**, and failure lands in PostHog as a `$mcp_*` event you can query, chart, alert on, and cluster — plus a dedicated dashboard. The MCP-layer sibling of `@posthog/ai`.

The differentiator is **intent**: not "ran `query_run` 14 times" but "was trying to find a churn cohort". Explicit non-goal: this does **not** replace LLM analytics / AI observability — generation traces, prompt/response, and token cost belong there.

Status: **beta**, TypeScript and Python SDKs shipped, whole product still behind the `mcp-analytics` early-access flag (`products/mcp_analytics/frontend/featurePreviewGate.ts`). PostHog dogfoods it — its own MCP server instruments itself, and that data drives the dashboard. Public tracking: mega-issue **PostHog/posthog#64016**, which is the live source for roadmap and customer wishlist.

Repos

GitHub is the source of truth for where the code lives. Paths below are in-repo; for the repos outside this monorepo, resolve a local checkout via [references/local-repos.md](references/local-repos.md) rather than assuming a location.

| Concern | Repo | Where to look | | --------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Product / dashboard** | `PostHog/posthog` (this repo) | `products/mcp_analytics/` — Django/DRF + HogQL query runners + Temporal, Kea frontend, the `query-mcp-*` tool registry, and the analysis skills | | **Self-instrumented server** | `PostHog/posthog` (this repo) | `services/mcp/` — PostHog's own MCP server (Hono); the dogfood event producer. Also hosts the _generated_ `query-mcp-*` handlers | | **Shared query reference** | `PostHog/posthog` (this repo) | [`models-mcp.md`](../../../posthog_ai/skills/querying-posthog-data/references/models-mcp.md) — `products/posthog_ai/skills/querying-posthog-data/references/` | | **TypeScript SDK** `@posthog/mcp` | `PostHog/posthog-js` | `packages/mcp/` — the library customers install. Vocabulary source of truth: `src/extensions/constants.ts`. `docs/ARCHITECTURE.md` now covers conversation anchoring (ADR-0004) but trails the newest era handling — where it and `CHANGELOG.md` disagree, trust the changelog and the source | | **Python SDK** `posthog.mcp` | `PostHog/posthog-python` | `posthog/mcp/` — mirrors `posthog.ai`. Ships inside `posthog` (`pip install posthog`); `mcp`/`fastmcp` are lazily-imported peer deps, **no `[mcp]` extra**. At TS parity since 7.40.0-7.42.1 — MCP Python SDK v2, conversation anchoring, typed errors, client UA/vendor | | **Docs** | `PostHog/posthog.com` | `contents/docs/mcp-analytics/` (incl. `surfaces/`), plus `src/hooks/productData/mcp_analytics.tsx` and the `mcp_analytics` entry in `src/data/tools.ts` | | **Install codemod** | `PostHog/context-mill` | `context/skills/mcp-analytics/{config.yaml,description.md}` | | **Wizard CLI** | `PostHog/wizard` | `bin.ts`, `src/commands/mcp-analytics.ts`, `src/lib/programs/mcp-analytics/` | | **Wizard test harness** | `PostHog/wizard-workbench` | `apps/mcp-analytics/` fixtures