# exploring-mcp-tool-usage

exploring-mcp-tool-usage — a routing skill for PostHog MCP analytics: it offers a menu of questions about tool calls, then hands you to the query that answers it.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 200 installs · ★ 101 repo stars
- Author: PostHog
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/PostHog/ai-plugin/tree/HEAD/skills/exploring-mcp-tool-usage/SKILL.md
- Updated: 2026-10-24
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/exploring-mcp-tool-usage

## What it does

This skill is where you start when you want to know how agents use your MCP server but have no specific question yet. It reads `$mcp_tool_call` events, which a server emits once it runs the `@posthog/mcp` SDK. Pick a question from the menu: failures, latency percentiles, top callers, neighbouring calls, agent intents. The skill points to the tool behind it.

The typed tools do the querying and reuse the query runner behind the tool-detail view in PostHog, so the numbers agree with the UI. `posthog:query-mcp-tool-stats` covers one tool's calls, errors, p50/p95, users and sessions; `posthog:query-mcp-tool-failures` lists its top error messages; `posthog:query-mcp-tool-top-users`, `posthog:query-mcp-tool-neighbors`, `posthog:query-mcp-tool-sample-intents`, `posthog:query-mcp-tool-daily-stats` and `posthog:query-mcp-harness-breakdown` handle the rest. Each takes a `toolName` and a `dateRange`. Pass the effective name, the inner tool of a wrapper call, except for `posthog:query-mcp-tool-failures`, which matches `$exception` events on the raw `$mcp_tool_name`.

Ask for a failure rate and the skill checks the governed metric first: `posthog:metric-list` for `mcp_tool_call_fail_pct`, then `posthog:data-catalog-metric-run` for the canonical number. Anything the typed tools don't cover, such as a cross-tool error ranking or sessions filtered by errors, goes through `posthog:execute-sql`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill exploring-mcp-tool-usage -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/exploring-mcp-tool-usage/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/exploring-mcp-tool-usage/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill exploring-mcp-tool-usage -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/exploring-mcp-tool-usage/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill exploring-mcp-tool-usage -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/exploring-mcp-tool-usage/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install PostHog/ai-plugin skills/exploring-mcp-tool-usage
```

2. **Manually: put the files in place**
- File: `.github/skills/exploring-mcp-tool-usage/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill exploring-mcp-tool-usage -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/PostHog/ai-plugin --path skills/exploring-mcp-tool-usage
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/exploring-mcp-tool-usage/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add PostHog/ai-plugin --skill exploring-mcp-tool-usage -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/PostHog/ai-plugin/tree/HEAD/skills/exploring-mcp-tool-usage/SKILL.md

## When to use it
- find which MCP tools fail most often
- check p50 and p95 latency for a single tool
- see who calls a tool most
- read what agents were trying to do before a call
- compare reliability across client harnesses

## Example prompts
- Which of my MCP tools fail the most?
- Who calls `search_docs` most over the last 7 days?
- Here is my MCP analytics URL, tell me what to look at

## Similar
- [exploring-llm-clusters](https://affpapa.org/en/nevibecode/skills/exploring-llm-clusters.md) — skill · 436 installs
- [exploring-llm-evaluations](https://affpapa.org/en/nevibecode/skills/exploring-llm-evaluations.md) — skill · 440 installs
- [omni-usage-logs](https://affpapa.org/en/nevibecode/skills/omni-usage-logs.md) — skill · 1300 installs
- [klingai-usage-analytics](https://affpapa.org/en/nevibecode/skills/klingai-usage-analytics.md) — skill · 1 install
- [cursor-usage-analytics](https://affpapa.org/en/nevibecode/skills/cursor-usage-analytics.md) — skill · 1 install
- [usage-trends](https://affpapa.org/en/nevibecode/skills/usage-trends.md) — skill · ★ 1198 repo stars

From the same set: [posthog/ai-plugin](https://affpapa.org/en/nevibecode/by/posthog/ai-plugin.md) — 82 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
