---
title: Tool-Usage Analytics
description: Per-deployment tool call volume, error rates, latency, and invocation history.
---

**Tool-usage analytics** answers: *which MCP tools is this server calling, how often, how fast, and how often do they fail?* — plus a searchable audit log of individual invocations.

Analytics are **per deployment**. Open a deployment in the dashboard and use the **Analytics** tab.

---

## What you can see

- **Call volume** — total tool calls over a time window (24h, 7d, 30d, or custom)
- **Error rates** — failed calls vs total, overall and per tool
- **Latency** — p50 and p95 tool-execution duration (milliseconds)
- **Per-tool breakdown** — leaderboard table and latency bars by tool name
- **Invocation log** — paginated, newest-first list of individual tool calls (expand a row for the raw audit payload)

---

## Honest limits (v1)

Keep these in mind when interpreting charts and planning workflows:

| Limit | Detail |
| :--- | :--- |
| **Latency is tool execution only** | Measured at the ToolHive proxy — how long the MCP server took to handle the call. It is **not** LLM latency or full client end-to-end time (the model runs in the user's client, which the platform never sees). Charts are labeled as tool execution time. |
| **No token or cost data** | Out of scope for v1. Do not expect token counts or dollar cost on this page. |
| **Near-real-time, not live** | Invocations arrive via a log pipeline with a few seconds of lag. Refresh or poll; there is no websocket/SSE live feed yet. |
| **One deployment at a time** | No project- or account-level rollups in v1. The sidebar **Analytics** item (account-wide) is separate and marked Coming Soon. |
| **No historical backfill** | Data starts when analytics collection is enabled for traffic. Empty state is normal for brand-new or quiet deployments. |

---

## Where in the UI

1. Open **Deployments** in the sidebar.
2. Select a deployment.
3. Open the **Analytics** tab.
4. Pick a time range and refresh as needed.

**Empty state:** "No tool calls recorded yet" means either no traffic yet, or no data in the selected window — not a broken page.

---

## API

Same Supabase session bearer auth as the rest of the dashboard API. Base URL: `https://api.mcplambda.io` (prod). Requests for a deployment you do not own return **404**.

### Tool usage (charts / KPIs)

```http
GET /v1/deployments/{id}/analytics/tool-usage?from=&to=&bucket=
```

| Query param | Default | Notes |
| :--- | :--- | :--- |
| `from` | now − 7 days | RFC3339, inclusive |
| `to` | now | RFC3339, exclusive |
| `bucket` | `day` | `minute` \| `hour` \| `day` \| `week` |

Response body (no `data` envelope) includes:

- `series` — rows per `(bucket_start, tool_name)` with `total_calls`, `error_calls`, `p50_duration_ms`, `p95_duration_ms`
- `summary` — per-tool aggregates over the whole window (use this for KPIs and the tools table)

`series` / `summary` may be `null` or `[]` when there is no data.

### Invocation audit log

```http
GET /v1/deployments/{id}/analytics/invocations?page=&page_size=
```

`page` is 1-based (default `1`); `page_size` defaults to `20`. Newest first. Each row includes tool name, outcome (`success` | `error`), duration, optional caller identity fields, and a raw `payload` for detail views.

---

## Operational tips

- Prefer **p50 and p95 together** — never rely on a bare average.
- High error rate on one tool often points at missing secrets, upstream API errors, or auth misconfiguration on that tool path.
- Use the invocation log when a single failed call needs the raw ToolHive audit record.

---

## Next steps

<Cards>
  <Card
    title="Getting Started"
    href="/docs/getting-started/"
    description="Deploy a server, then watch traffic on Analytics."
  />
  <Card
    title="Deployment Strategies"
    href="/docs/deployment-strategies/"
    description="Package, Git, Docker, and registry install paths."
  />
  <Card
    title="Server Profiles"
    href="/docs/profiles/"
    description="Size deployments with Compute Units."
  />
  <Card
    title="Connecting AI Clients"
    href="/docs/ai-clients/"
    description="Generate real tool traffic from Cursor, VS Code, or Claude."
  />
</Cards>