---
title: mcp
description: clawmetry mcp — start the Model Context Protocol server that lets coding agents query their own ClawMetry telemetry over stdio.
keywords: clawmetry mcp server, MCP agent telemetry, Claude Code MCP, agent self diagnosis
eyebrow: CLI reference
---

# `clawmetry mcp`

Start the ClawMetry MCP server on stdio, so an agent can query its own
telemetry.

```bash
clawmetry mcp
```

No flags. The server speaks newline-delimited JSON-RPC 2.0 over stdin and
stdout, implementing MCP `2024-11-05`. It is meant to be launched by an MCP
client, not run by hand — though running it by hand is a perfectly good way to
check it works.

## What it exposes

Five tools:

| Tool | Answers |
|---|---|
| `list_sessions` | What have I been running? |
| `get_cost_summary` | What did it cost over this window? |
| `get_session_trace` | What happened inside one session? |
| `list_events` | Raw events, filtered by session, type or time |
| `get_health` | Is the ClawMetry daemon itself healthy? |

Full argument reference: [MCP tool reference](/docs/mcp/tools/).

## Registering it

```bash title="Claude Code"
claude mcp add clawmetry -- clawmetry mcp
```

```json title="Any MCP client, by config"
{
  "mcpServers": {
    "clawmetry": {
      "command": "clawmetry",
      "args": ["mcp"]
    }
  }
}
```

More clients, and the per-client paths: [Connect the MCP server](/docs/mcp/install/).

## How it reads data

The server does **not** open DuckDB. It reads the daemon's discovery file at
`~/.clawmetry/local_query.json`, checks the recorded pid is actually alive, and
posts queries to the daemon's localhost query server with the bearer token from
that file.

That has three consequences worth knowing:

1. **The daemon must be running.** With no daemon, every tool returns
   `{"error": "ClawMetry daemon is not running. Start it with: clawmetry sync"}`
   rather than an empty result that looks like "you did nothing this week".
2. **No lock contention.** The MCP server never competes with the daemon for the
   writer lock, so an agent hammering it cannot slow ingest.
3. **It is local.** The transport is loopback with a token. Nothing about MCP
   opens a network surface.

## Checking it by hand

```bash
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | clawmetry mcp
```

You should get a JSON-RPC response listing the five tools. If you get the
daemon-not-running error instead, start the daemon first.

## Why this exists

An agent that can read its own history can answer questions no external
dashboard can, because it knows what it was *trying* to do. "Have I hit this
error before?" and "am I repeating a session that already failed?" are cheap
questions with the history and impossible without it.

The recipes are in [Self-diagnosis](/docs/mcp/self-diagnosis/).