skills.rest
PostHog
PostHogOFFICIAL
Explore all skills by this author ā†’
Websiteš•@PostHogGitHub

debugging-mcp-analytics

Diagnose missing or incorrect PostHog MCP analytics events, sessions, and intent clusters.

713|118|Updated Aug 11, 2020
Search Tags:#mcp#session tracking#Debugging#PostHog#product analytics#event instrumentation#HogQL
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill debugging-mcp-analytics
Or copy as Structured Prompt for Agentā–¼
Please help me install this Agent Skill.
Skill: debugging-mcp-analytics
Source: https://github.com/PostHog/posthog-foss/tree/main/products/mcp_analytics/skills/debugging-mcp-analytics
Command: npx skills add https://github.com/PostHog/posthog-foss --skill debugging-mcp-analytics

SYSTEM DOCUMENTATION & REQUIREMENTS

šŸ’” This Skill includes references (resource) components.

What problem does it solve?

MCP analytics data can silently look wrong ā€” events missing, intent clusters empty, sessions fragmented, per-tool numbers off ā€” and each symptom has a specific, non-obvious cause spread across SDKs, the dashboard query runners, and PostHog's own dogfood server. This Skill maps the entire pipeline so you can find and fix the actual break instead of guessing.

Core Features & Use Cases

  • Repo and pipeline map: Identifies which repository owns each concern (TypeScript SDK in posthog-js, Python SDK in posthog-python, product in the monorepo, wizard install flow) and where each pipeline stage breaks.
  • Hard rules for correct queries: Encodes the failure modes that produce plausible-but-wrong numbers, such as resolving tool names through EFFECTIVE_TOOL_SQL, reading failures from $mcp_is_error rather than $exception, and dashing in-progress time buckets.
  • Event vocabulary reference: Documents every $mcp_* event and property by provenance (SDK-emitted, server-stamped, exec-mode) with per-version SDK behavior for both TypeScript and Python.
  • Use Case: A customer reports their intent clusters are empty. Use this Skill to learn that empty clusters almost always mean no $mcp_intent values in the lookback window, then check the corpus before chasing summary generation or the Temporal schedule.

Quick Start

Ask the agent to debug why MCP analytics sessions appear fragmented for a stateless MCP server using this Skill.

Frequently Asked Questions about debugging-mcp-analytics

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why are my MCP analytics events not showing up in PostHog?ā–¼

Missing MCP events usually mean handlers were not wrapped by instrument(), a STDIO server is corrupting the protocol stream with console output, or the posthog client is disabled. For MCP TypeScript SDK v2 servers, SDK versions before 0.10.9 silently produced zero events.

How do I query MCP tool call failures in PostHog?ā–¼

Query failures using $mcp_is_error, $mcp_error_type, and $mcp_error_status on $mcp_tool_call events, never $exception. The $exception event can be disabled and is not emitted when no error value is passed, so querying it returns nothing rather than failing.

Why are MCP sessions fragmented into one session per request?ā–¼

Fragmented sessions on a stateless MCP client almost always mean enableConversationId is off, which is the default. Without it there is no transport session and no conversation handle, so $session_id falls back to in-memory resolution that fragments per request.

Does the PostHog MCP analytics SDK support Python servers?ā–¼

Yes, the posthog.mcp module ships inside the posthog Python package and reached TypeScript parity in versions 7.40.0 through 7.42.1. It supports MCP Python SDK v2, conversation-anchored sessions, typed error properties, and user-agent capture.

Why are MCP intent clusters empty in the dashboard?ā–¼

Empty intent clusters almost always mean no $mcp_intent values exist in the lookback window, so check the corpus before investigating summary generation. Also verify the mcp-analytics-intent-routing flag is on and note the daily schedule currently covers only hard-coded team IDs.

Related Skills

Explore More Software Engineering Skillsā†’
october-academyoctober-academy
1

analytics-setup

Guide PostHog installation and define core events for analytics readiness.

Official
Intermediate
MoonAxisMoonAxis

azure-kusto

Query Azure Data Explorer clusters using Kusto Query Language.

Official
Intermediate
anthropicsanthropics
23.8k

zoom-meeting-sdk-electron

Implements Zoom Meeting SDK integration in Electron desktop apps with JWT auth and join flows.

Official
Advanced
PostHogPostHog
58

omnibus-instrument-llm-analytics

Instrument LLM calls with PostHog LLM Analytics to capture token counts, latency, and costs.

Official
Advanced