---
title: MCP tool reference
description: Complete reference for the five ClawMetry MCP tools — arguments, defaults, limits, the query shape each one maps to, and the JSON-RPC calls behind them.
keywords: MCP tool reference, list_sessions, get_cost_summary, get_session_trace, list_events, agent telemetry API
eyebrow: Agents & MCP
---

# MCP tool reference

Five tools. Each maps onto a shape in the [query contract](/docs/data/query-api/),
so what the agent sees and what the HTTP API returns are the same rows.

Protocol: JSON-RPC 2.0, newline-delimited, MCP `2024-11-05`, over stdio.

---

## `list_sessions`

List recent agent sessions. Each row carries the session id, model, token usage,
cost and status.

| Argument | Type | Default | Notes |
|---|---|---|---|
| `limit` | integer | `20` | Maximum sessions to return; the store caps at 2000 |
| `since` | string | — | ISO 8601 timestamp; return sessions after this |

Maps to the `sessions` shape.

```json
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
  "name":"list_sessions","arguments":{"limit":50,"since":"2026-09-01T00:00:00Z"}}}
```

**Use it for:** "what have I been running", "did I already work on this",
"which sessions were expensive".

---

## `get_cost_summary`

Aggregated token and cost totals: input, output, cached tokens and USD.

| Argument | Type | Default | Notes |
|---|---|---|---|
| `since` | string | — | ISO 8601 start of the window |
| `until` | string | — | ISO 8601 end of the window |

Maps to the `aggregates` shape, which is a per-day rollup — so a wide window is
cheap.

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"get_cost_summary","arguments":{"since":"2026-08-01T00:00:00Z"}}}
```

**Use it for:** "what did this week cost", "is my spend trending up", "how much
have I already spent on this problem".

---

## `get_session_trace`

Every event in one session — messages, tool calls, results, errors, timing.

| Argument | Type | Default | Notes |
|---|---|---|---|
| `session_id` | string | — | **Required** |
| `limit` | integer | `500` | Maximum events; the store caps at 5000 |

Maps to the `transcript` shape.

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"get_session_trace","arguments":{"session_id":"…","limit":1000}}}
```

**Use it for:** "what actually happened in that failed run", "what did the agent
do just before the error", "reconstruct the working approach from the run that
succeeded".

---

## `list_events`

Raw events across sessions, filtered.

| Argument | Type | Default | Notes |
|---|---|---|---|
| `session_id` | string | — | Scope to one session |
| `event_type` | string | — | e.g. `message`, `tool_call`, `tool_result`, `error` |
| `since` | string | — | ISO 8601 start |
| `limit` | integer | `200` | Maximum events; the store caps at 5000 |

Maps to the `events` shape.

```json
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{
  "name":"list_events","arguments":{"event_type":"error","since":"2026-09-04T00:00:00Z","limit":100}}}
```

**Use it for:** the cross-cutting questions. "Every error in the last day",
"every call to this tool this week", "how often does this fail".

This is the most flexible of the five, and the one worth teaching an agent to
reach for.

---

## `get_health`

Daemon health: store size, session count, last sync time, ingestion rate. No
arguments.

```json
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{
  "name":"get_health","arguments":{}}}
```

**Use it for:** deciding whether an empty result means "nothing happened" or
"ClawMetry is behind". An agent that checks this before trusting an empty
`list_sessions` is a well-behaved one.

---

## Errors

Every tool returns an error object rather than throwing:

```json
{"error": "ClawMetry daemon is not running. Start it with: clawmetry sync"}
```

That specific message is the one to expect when the daemon is down or its
discovery file is stale. It is deliberately not an empty result — an agent shown
an empty session list will conclude you did no work, and act on that.

## Limits

The store enforces its own caps regardless of what an agent asks for:

| Shape | Default | Maximum |
|---|---|---|
| `sessions` | 100 | 2000 |
| `events` | 200 | 5000 |
| `transcript` | 500 | 5000 |

An agent asking for a million events gets the cap, not an error.

## Beyond these five

The MCP surface is a curated subset. The full query contract has thirteen live
shapes — spans, traces, external calls, per-model rollups, per-runtime rollups,
full-text search, the agent graph. If an agent needs one of those, the HTTP API
is right there and it can `curl` it:

```bash
curl -s localhost:8900/api/local/query -X POST \
  -H 'content-type: application/json' \
  -d '{"shape":"search","args":{"q":"IntegrityError","limit":20}}'
```

→ [Query API](/docs/data/query-api/)