posthog/ai-plugin

exploring-mcp-tool-usage

Starting point for exploring how a PostHog MCP server's tools are used — routes a broad question to the typed tool that answers it.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/posthog/ai-plugin --skill exploring-mcp-tool-usage

Prima di iniziare

  • L’installazione non include abbonamenti, quote API o accesso ai file.
  • Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Documento Skill originale

Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.

Exploring MCP tool usage

Any MCP server instrumented with the @posthog/mcp SDK emits a $mcp_tool_call event every time an agent invokes a tool. This skill is the front door for a user who knows they want to look at their MCP tool usage but hasn't picked a specific question. Offer the menu below, then route to the tool — or the focused skill — that answers what they choose.

Every per-tool tool here is gated behind the mcp-analytics flag, takes a toolName (the effective tool name — resolved server-side, so pass the name the agent actually invokes — except `posthog:query-mcp-tool-failures`, which matches $exception events and so takes the raw registered $mcp_tool_name) plus a dateRange, and runs the same query runner the tool-detail UI uses. So results match the UI, and you never hand-write the HogQL.

Suggested questions

Lead with these when the user is unsure what to ask:

Ask the user…Answered by
"Which tools fail most, or are slowest?"exploring-mcp-tool-quality (ranks all tools), then posthog:query-mcp-tool-stats to drill in
"How is tool X doing overall?"posthog:query-mcp-tool-stats — calls, errors, p50/p95, users, sessions, intents
"How has tool X trended?"posthog:query-mcp-tool-daily-stats — day-by-day series
"Why is tool X failing?"posthog:query-mcp-tool-failures — top error messages, by harness (raw tool name)
"Who uses tool X the most?"posthog:query-mcp-tool-top-users — top callers (incl. person email/name)
"What gets called right before/after tool X?"posthog:query-mcp-tool-neighbors (neighborDirection: before/after)
"What are agents trying to do with tool X?"posthog:query-mcp-tool-sample-intents — recent agent intents
"What description is tool X registered with?"posthog:query-mcp-tool-descriptions — distinct descriptions seen
"Which harnesses use my MCP, how reliably?"posthog:query-mcp-harness-breakdown — calls/errors/sessions per client
"What are agents trying to do, across all tools?"exploring-mcp-intent-clusters — semantic goal clusters
"Who is connecting, and how active are they?"posthog:mcp-analytics-sessions-list — one row per session, with client and person
"What did this one session do?"exploring-mcp-sessions — a single agent run's tool sequence

Finding the tool name

The per-tool tools need a toolName. If the user named a tool, pass it. If they asked a broad "which tool…" question, start with exploring-mcp-tool-quality to rank the tools, pick the one that stands out, then drill in with the per-tool tools above. The name to pass is the effective tool name (the inner tool for single-exec wrapper calls) — the same string the tool-quality ranking returns. The one exception is posthog:query-mcp-tool-failures, which matches $exception events by the raw registered $mcp_tool_name, not the effective inner tool.

How to use a per-tool tool

Call it with the tool name and a window, e.g. for the headline numbers of a tool:

text
posthog:query-mcp-tool-stats  { "toolName": "<tool>", "dateRange": { "date_from": "-7d" } }

Then offer a natural follow-up from the menu — e.g. after posthog:query-mcp-tool-stats shows a high error rate, reach for posthog:query-mcp-tool-failures; after it shows broad reach, reach for posthog:query-mcp-tool-top-users or posthog:query-mcp-tool-neighbors.

When to drop to SQL

Covered by a typed tool — don't hand-write SQL for these:

QuestionTool
One tool's headline numbersposthog:query-mcp-tool-stats
One tool's day-by-day trendposthog:query-mcp-tool-daily-stats
One tool's top errorsposthog:query-mcp-tool-failures
One tool's top callersposthog:query-mcp-tool-top-users
Tools called before/after one toolposthog:query-mcp-tool-neighbors
One tool's recent agent intentsposthog:query-mcp-tool-sample-intents
One tool's registered descriptionsposthog:query-mcp-tool-descriptions
Usage split by client harnessposthog:query-mcp-harness-breakdown
List sessionsposthog:mcp-analytics-sessions-list
One session's tool callsposthog:mcp-analytics-sessions-tool-calls

Not covered — use `posthog:execute-sql`:

  • Cross-tool rankings (the tool-quality matrix — "which tool errors most?")
  • Errored-session filtering (the session list has no error filter or error count)
  • Effective tool names inside a session (posthog:mcp-analytics-sessions-tool-calls

returns the raw $mcp_tool_name, not the inner tool of a wrapper call)

  • Any custom breakdown

posthog:execute-sql is also the fallback when the mcp-analytics flag is off — every tool in the table above is gated behind it, execute-sql is not. Query $mcp_tool_call directly; the schema and recipes are in `models-mcp.md`.

Related skills

tools by error rate / latency / reach, then drill in

run and its tool sequence

agent goals grouped by semantic similarity

Correlati per attività

dallo stesso repository

Altri Skills

Tutti gli Skills
posthog
Ufficiale

exploring-llm-costs

Investigate LLM spend in PostHog — total cost over time, cost by model, provider, user, trace, or custom dimension, token and cache-hit economics, and cost regressions. Use when the user asks "how much are we spending on LLMs?", "which model / user / feature is most expensive?", "why did cost spike?", wants to build a cost dashboard or alert, or pastes a trace URL and asks about its cost.

Installazioni / 1h
2
GitHub Stars
98
Aggiornato
6 nov
posthog
Ufficiale

exploring-llm-traces

Debug and inspect LLM/AI agent traces using PostHog's MCP tools. Use when the user pastes a trace or session URL (e.g. /ai-observability/traces/ or /ai-observability/sessions/ ), asks to debug a trace, figure out what went wrong, check if an agent used a tool correctly, verify context/files were surfaced, inspect subagent behavior, investigate LLM decisions, or analyze token usage and costs. Also use when raw SQL/HogQL against events.properties.$aiinput / $aioutputchoices returns empty — message

Installazioni / 1h
2
GitHub Stars
98
Aggiornato
6 nov
posthog
Ufficiale

instrument-integration

Add PostHog SDK integration to your application. Use when setting up PostHog for the first time or reviewing PRs that need PostHog initialization. Covers SDK installation, provider setup, and basic configuration for any framework.

Installazioni / 1h
2
GitHub Stars
98
Aggiornato
6 nov
posthog
Ufficiale

investigating-error-issue

Investigates a single PostHog error tracking issue end-to-end. Use when the user provides an issue ID or pastes an issue URL (/error-tracking/ ) and wants to understand the error — who it affects, what triggers it, when it started, whether it correlates with a release, browser, OS, or feature flag, and what the next step should be. Pulls aggregated metrics, sample exception events, segment breakdowns, linked replays, and synthesizes a hypothesis-grade summary in one pass.

Installazioni / 1h
2
GitHub Stars
98
Aggiornato
6 nov