Telemetry
Leaderboards#
The unified agent-connector leaderboard prints three origin-labeled boards that measure different things and are NEVER summed. Each has its own prerequisite, so for any given person some boards may be empty — read the PREREQUISITE column.
Agent users: use `usage`, not this unified board
Only the 🖥️ Host/User board works with no setup. If you haven't authored a connector, the connector-freeagent-connector usage command is your primary entry point — it draws from the same connector-free host-scan source.| Board | Origin | Measures | Prerequisite |
|---|---|---|---|
| 🔌 MCP / Plugin | mcp-self | Serve-proxy telemetry (per-MCP call + tool_defs rows; excludes host-native model_turn rows). "Which MCP server costs the most tokens" — for a server your own connector declares and wraps. | A registered connector + serve traffic (stdio). Empty for an agent user with no connector. |
| 🖥️ Host / User | host-scan-logs | Host usage from scanning CLI logs. "Which CLI/host spent the most." Whole-conversation totals only — no per-MCP/per-tool dimension. | None — works with no setup. The only board an agent user sees. |
| 🛰️ Host-native turns | host-native-live | The opt-in AfterModel / PostInvocation usage hook (scope model_turn, confidence host-native). Whole-conversation, live and exact. | The opt-in usage hook, installed only by the Gemini CLI and Antigravity adapters, and requires --connector at runtime. |
The unified command agent-connector leaderboard --scope <slice> slices only the MCP section; --json emits { mcp, host, hostSkipped, hostNativeTurns }. The scope dimension applies to the MCP board, letting you narrow per-MCP rows to a slice without affecting the host boards.
$ agent-connector leaderboard --since 7d
🔌 MCP / Plugin (origin: mcp-self)
1. acme-db 12.4k calls 4.81M tok tokenizer-exact
2. weather 3.1k calls 0.92M tok tokenizer-exact
3. github 2.7k calls 0.74M tok tokenizer-approx
🖥️ Host / User (origin: host-scan-logs)
1. claude-code @ macbook 18.2k 5.10M tok host-reported
2. cursor @ macbook 4.4k 1.12M tok host-estimated
🛰️ Host-native turns (origin: host-native-live)
1. gemini-cli @ devbox 1.2k 2.04M tok host-native
# the three boards measure DIFFERENT things — never summed.Scoped to your connector#
As a connector developer you usually want only your connector's usage. Pass --connector <id> to filter the 🔌 MCP/Plugin section — and that is exactly what a branded CLI injects for you: <your-tool> leaderboard ≈ agent-connector leaderboard --connector <id>. The 🖥️ Host/User board stays connector-agnostic (host CLI logs carry no connector attribution), so only the 🔌 MCP/Plugin and 🛰️ host-native sections are filtered.
# as a connector developer, scope the leaderboard to YOUR connector:
$ acme-db leaderboard --since 7d
# ≈ agent-connector leaderboard --connector acme-db --since 7d
🔌 MCP / Plugin (origin: mcp-self · connector: acme-db)
1. acme-db 12.4k calls 4.81M tok tokenizer-exact
# ^ only acme-db rows — other connectors are filtered out
# per-tool, still scoped to acme-db:
$ acme-db telemetry leaderboard --by tool
# ≈ agent-connector telemetry leaderboard --by tool --connector acme-db
# NOTE: the 🖥️ Host/User section stays connector-agnostic — host CLI logs carry
# no connector attribution, so only the 🔌 MCP/plugin (+ 🛰️ host-native) sections
# are filtered to acme-db.For the developer/connector axis there is also agent-connector telemetry leaderboard --by mcp|tool|surface: the --by surface variant ranks across the five developer surfaces (server + hook runtime rows plus the static command/skill/subagent footprints), with the columns SURFACE | NAME | IN | OUT | TOTAL | KIND.
Why two non-summed boards
Per-MCP server bytes (🔌) measure your server's own I/O; host/user usage (🖥️) measures whole-conversation usage from CLI logs; live host-native turns (🛰️) are whole-conversation usage from a real-time hook. These are different things — totals are never added across origins. (For the per-MCP vs host-scan distinction specifically, see the canonical explanation.)