Agents & MCP

Connect the MCP server#

The server is clawmetry mcp — a stdio process your client launches. There is no port to open and no service to run separately.

Prerequisites#

The ClawMetry daemon must be running, because the MCP server reads through it.

bash

clawmetry status     # daemon: running

If it is not: clawmetry sync.

Claude Code#

bash

claude mcp add clawmetry -- clawmetry mcp

Verify:

bash

claude mcp list

Then, inside Claude Code, ask it something only ClawMetry knows — "using clawmetry, how many sessions did I run yesterday?" — and check it calls the tool rather than guessing.

Any client, by configuration#

Most MCP clients take the same JSON shape. The file location differs; the block does not.

json

{
  "mcpServers": {
    "clawmetry": {
      "command": "clawmetry",
      "args": ["mcp"]
    }
  }
}

If clawmetry is not on the PATH your client sees — common with GUI apps on macOS, which do not inherit your shell environment — use the absolute path:

json

{
  "mcpServers": {
    "clawmetry": {
      "command": "/opt/homebrew/bin/clawmetry",
      "args": ["mcp"]
    }
  }
}

Find it

which clawmetry

Cursor#

Add the same block to Cursor's MCP configuration, then restart Cursor. Cursor launches MCP servers itself, so a server added while it is running is not picked up until it restarts.

Codex, Goose, opencode and others#

All of them accept a stdio server with a command and arguments. Use the block above; consult the client for where its configuration file lives.

Pointing at a different machine#

The MCP server reads the local daemon. To query a different machine's telemetry, run the MCP server there — over SSH, for instance:

json

{
  "mcpServers": {
    "clawmetry-build-box": {
      "command": "ssh",
      "args": ["build-box", "clawmetry", "mcp"]
    }
  }
}

The stdio transport passes cleanly over SSH, which makes this the simplest way to give a local agent visibility into a remote fleet node.

Verify by hand#

bash

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

You should see five tools. Then try a real call:

bash

printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_health","arguments":{}}}' \
  | clawmetry mcp

Troubleshooting#

Symptom	Cause	Fix
Every tool returns "daemon is not running"	The daemon is down, or its discovery file is stale	`clawmetry sync`
Client cannot start the server	`clawmetry` not on the client's `PATH`	Use the absolute path from `which clawmetry`
Tools list is empty	The client did not complete the handshake	Restart the client; check its MCP log
Results are empty but no error	The store genuinely has nothing in that window	Widen `since`, and check `clawmetry status` for ingest progress
Server was added but the agent ignores it	The agent does not know it should use it	Name it in the prompt, or add a skill

The discovery file#

For reference, the server finds the daemon here:

~/.clawmetry/local_query.json

{"port": 51843, "token": "…", "pid": 4711}

It checks the pid is alive before trusting the port, so a stale file left by a crashed daemon produces the honest "not running" error rather than a connection attempt against whatever else has since taken that port.

Edit this page View as Markdown Report an issue