CClawMetryDocs

Agents & MCP

MCP tool reference#

Five tools. Each maps onto a shape in the query contract, 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.

ArgumentTypeDefaultNotes
limitinteger20Maximum sessions to return; the store caps at 2000
sincestring—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.

ArgumentTypeDefaultNotes
sincestring—ISO 8601 start of the window
untilstring—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.

ArgumentTypeDefaultNotes
session_idstring—Required
limitinteger500Maximum 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.

ArgumentTypeDefaultNotes
session_idstring—Scope to one session
event_typestring—e.g. message, tool_call, tool_result, error
sincestring—ISO 8601 start
limitinteger200Maximum 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:

ShapeDefaultMaximum
sessions1002000
events2005000
transcript5005000

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

Edit this page View as Markdown Report an issue
Cookie preferences