posthog/exploring-mcp-tool-usage
skills/exploring-mcp-tool-usage/SKILL.md
Starting point for exploring how a PostHog MCP server's tools are used — routes a broad question to the typed tool that answers it. Use when the user asks "how is my MCP doing?", "what should I look at?", "explore my tool calls", "who uses my MCP tools?", "what are agents doing with the MCP?", or pastes an MCP analytics URL without a specific question. Offers a menu of questions, each backed by a query tool, then hands off to the focused skill.
$ install --global
skillsauthnpx skillsauth add posthog/ai-plugin exploring-mcp-tool-usageInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Jul 18, 2026, 6:10 AM381.0s1 file scanned
SKILL.md
- name:
- exploring-mcp-tool-usage
- description:
- >
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:
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:
| Question | Tool |
| ---------------------------------- | ------------------------------------------- |
| One tool's headline numbers | posthog:query-mcp-tool-stats |
| One tool's day-by-day trend | posthog:query-mcp-tool-daily-stats |
| One tool's top errors | posthog:query-mcp-tool-failures |
| One tool's top callers | posthog:query-mcp-tool-top-users |
| Tools called before/after one tool | posthog:query-mcp-tool-neighbors |
| One tool's recent agent intents | posthog:query-mcp-tool-sample-intents |
| One tool's registered descriptions | posthog:query-mcp-tool-descriptions |
| Usage split by client harness | posthog:query-mcp-harness-breakdown |
| List sessions | posthog:mcp-analytics-sessions-list |
| One session's tool calls | posthog: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-callsreturns 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
exploring-mcp-tool-quality— rank tools by error rate / latency / reach, then drill inexploring-mcp-sessions— a single agent run and its tool sequenceexploring-mcp-intent-clusters— agent goals grouped by semantic similarity
Related Skills
posthog/signals-scout-tasks
data-ai
VerifiedTrustedCommunity
Signals scout for PostHog Tasks, the agent work items a project runs. Two lenses: delivery health (runs failing, clustered by repository and error class, and retry storms) every run, and on a slower rotation demand (recurring asks across human-authored tasks that point at a product gap). Skips the scout fleet's own run rows.
65SKILL.mdUpdated Jul 29, 2026
posthog/signals-scout-conversations
devops
VerifiedTrustedCommunity
Signals scout for the PostHog Conversations (support inbox) product. Watches the `$conversation_*` ticket-lifecycle events for support-delivery regressions — SLA breach-rate steps, first-response latency blowouts, backlog inflow-vs-resolution imbalance, and channel / assignment concentration — and files each dated regression as a report. Complements the per-ticket product-feedback signals the emission pipeline already fires; does not re-surface individual ticket content.
65SKILL.mdUpdated Jul 29, 2026
posthog/setting-up-data-catalog
development
VerifiedTrustedCommunity
Populates and maintains a project's data catalog (semantic layer): canonical metrics, trust marks (certifications) on warehouse tables/views, and reviewed table relationships. Use when asked to set up / seed / bootstrap the data catalog or semantic layer, to catalog a project's metrics, to certify or deprecate data sources, to propose or review table joins, or to work through the proposal review queue. To *use* an existing catalog to answer a business-number question, see querying-posthog-data instead. Trigger terms: data catalog, semantic layer, canonical metric, certify table, deprecate source, relationship proposal, metric drift, review queue.
65SKILL.mdUpdated Jul 29, 2026
posthog/investigating-logs
tools
VerifiedTrustedCommunity
Investigate logs in a PostHog project: verify a service or deployment is healthy, explain an error spike, triage an incident, or understand what a log stream is saying. Use when the user asks to "check the logs", asks whether a service, deploy, release, or change is working or broke anything, asks why errors are up or what changed, or wants the root cause of failures visible in logs. Routes the logs MCP tools (services overview, pattern mining, before/after pattern diffing, bucketed counts, facets, raw rows) so investigations start from summaries instead of raw rows or hand-written SQL over the logs table.
65SKILL.mdUpdated Jul 29, 2026