---
title: Connect the MCP server
description: Register ClawMetry's MCP server with Claude Code, Cursor, Codex, Goose and any other MCP client — with verification steps and the troubleshooting table.
keywords: add MCP server Claude Code, Cursor MCP config, clawmetry mcp setup, MCP server configuration
eyebrow: 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"]
    }
  }
}
```

```bash title="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](/docs/mcp/skills/) |

## The discovery file

For reference, the server finds the daemon here:

```json title="~/.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.