# Tracing & debugging MCP

Tell overlapping MCP processes apart and inspect tool calls.

Every editor spawns its own `bookmark-context mcp` process at session start, so
several run at once and the OS process list can't tell them apart.

## Always on — `/stats`

`GET /stats` reports each process with `client` (`cursor`, `claude-code`, or
`unknown`, inferred from the parent process chain), `started_at`, `ppid`,
`parent_name`, and `uptime_seconds`. The extension's memory tooltip in the
status footer shows one line per MCP server. Nothing is written to disk.

## Opt-in — spawn / exit events

```
BOOKMARK_CONTEXT_TRACE=1
```

or `[trace] processes = true`. Appends one line per process start and stop to
`~/.local/share/bookmark-context/trace/processes.jsonl`.

## Opt-in — tool calls

```
BOOKMARK_CONTEXT_MCP_TRACE=1
```

or `[trace] mcp_tools = true` (also enabled by `BOOKMARK_CONTEXT_TRACE=1`).
Appends tool name, duration, and outcome to `trace/mcp-tools.jsonl`.

Queries are recorded as a **length, never text**; a failure logs the exception
type without its message. Both logs rotate at 1 MB and keep one `.jsonl.1`
archive. Environment variables override the config file.

## Raw protocol

For a JSON-RPC problem rather than a behavioural one, run `mcp_debug.py` as a
stdio proxy in place of the server:

```json
{ "command": "python3", "args": ["/path/to/bookmark-context/mcp_debug.py"] }
```

It logs full message bodies — queries included — to `/tmp/mcp_raw.log`. Put the
normal command back when you're done.