: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.
MCP development guide
Commands
Run these commands from the repository root:
- Run
pnpm --filter=@posthog/mcp run typecheckafter changing TypeScript or TSX files. It checks types without emitting files. - Run
pnpm --filter=@posthog/mcp run formatto apply Oxfmt only. Uselintandformat:checkfor verification; neither command rewrites files. - Run
pnpm --filter=@posthog/mcp run lint:fixto apply safe Oxlint fixes. It does not apply suggestion fixes that may change behavior. - Run
pnpm --filter=@posthog/mcp run fixbefore committing JavaScript, TypeScript, JSON, YAML, CSS, or SCSS changes. It applies safe Oxlint fixes, always runs Oxfmt, and fails if either tool fails.
Unsolicited elicitation: high risk
[!CAUTION] Elicitation can spam users and damage trust in the MCP. It can interrupt an agent mid-task and put advertising or research questions directly in front of the user. The interview recruitment flow is a narrow exception. It does not establish permission to add more prompts.
- New unsolicited elicitation requires explicit approval from a human MCP owner before implementation.
[review]This includes surveys, recruitment, upsells, promotional questions, and reusing the interview flow for another purpose. A general request to improve the MCP does not authorize these interruptions. - Expanding an existing prompt's reach or frequency, or weakening its opt-out behavior, requires the same approval.
[review]Review must justify the interruption's user value, audience, timing, frequency, reliable suppression, and measurement. A feature flag or client capability alone does not justify showing a prompt. - Read the interview recruitment guide before changing unsolicited elicitation. It documents the existing flow's capability checks, exclusions, warmup, suppression, and analytics. Preserve those protections when fixing or maintaining it.
This policy covers unsolicited interruptions. Elicitation needed to complete the user's requested task, such as a necessary clarification or confirmation, remains a separate use case.
MCP Analytics
- Before adding or changing MCP Analytics instrumentation, read the tracking and observability architecture.
- Prefer
@posthog/mcp-analyticsfor all MCP telemetry it supports. The SDK should own reusable MCP Analytics behavior. Server code should only provide the relevant typed data and PostHog-specific integration. - Do not duplicate SDK behavior with custom event capture, property mapping, session handling, identity handling, or other parallel instrumentation.
- Event and property names beginning with
$mcp_are owned by MCP Analytics SDKs. Do not invent, add, rename, reinterpret, or manually populate$mcp_*fields in server code unless the SDK explicitly exposes them for that purpose. - Before introducing a new MCP Analytics event, property, or concept, check whether the SDK already supports it or whether it belongs in the SDK.
- If the SDK does not support a required signal or event, discuss the design with
@team-mcp-analyticsin Slack (#team-mcp-analytics) before implementing it. Prefer extending the SDK when the signal could be useful to other MCP Analytics customers. A custom event can be more appropriate for a product-specific or one-off need, but sync with the team first. - Assign
PostHog/mcp-analyticsas a reviewer on every PR that changes MCP Analytics instrumentation. - In the PR description, include a short MCP Analytics note that summarizes the changed analytics behavior, why it is needed, and whether it uses existing SDK support or requires something new.