# Tracing MCP tools

> Reference for the tracing tools in the Divergent MCP server, with each tool's parameters and response.

The [Divergent MCP server](https://docs.divergentlabs.xyz/compute/mcp.md) provides the operations of [`div traces`](https://docs.divergentlabs.xyz/tracing/cli/traces.md), [`div trace`](https://docs.divergentlabs.xyz/tracing/cli/trace.md), [`div score`](https://docs.divergentlabs.xyz/tracing/cli/score.md) and [`div scores`](https://docs.divergentlabs.xyz/tracing/cli/scores.md) as tools. Setup is on [that page](https://docs.divergentlabs.xyz/compute/mcp.md). The API key needs the `traces:read` scope to read, and `traces:write` to delete a trace and to set or delete a score. A key from `div login` has both.

Responses are JSON.

## Tools

| Tool | Description |
| --- | --- |
| [`list_traces`](#list_traces) | List the org's traces, newest first. |
| [`get_trace`](#get_trace) | Return a trace and its spans, without their content. |
| [`get_span`](#get_span) | Return one span in full. |
| [`delete_trace`](#delete_trace) | Delete a trace, its spans and its scores. |
| [`score_trace`](#score_trace) | Set a score on a trace or one of its spans. |
| [`delete_score`](#delete_score) | Delete a score. |
| [`list_scores`](#list_scores) | List the org's scores. |
| [`list_score_changes`](#list_score_changes) | Return the changes to the org's scores after a seq. |

A typical session: `list_traces` with `errors: true`, `get_trace` on one of them, then `get_span` on the span that failed.

## list_traces

Lists the org's traces, newest first by when tracing received them.

| Parameter | Type | Description |
| --- | --- | --- |
| `since` | string | Only traces received after: `30m`, `1h`, `7d`, a date or an ISO 8601 time. |
| `until` | string | Only traces received before, in the same forms. |
| `name` | string | Only traces with this root span name. |
| `session` | string | Only traces with this session id. |
| `user` | string | Only traces with this user id. |
| `environment` | string | Only traces from this `deployment.environment`. |
| `service` | string | Only traces with a span from this `service.name`. |
| `model` | string | Only traces with a span that called this model. |
| `errors` | boolean | Only traces with a span that ended in an error. |
| `limit` | integer | Number of traces, 1 to 200. Default 50. |
| `score` | string | Only traces with a score that passes, such as `helpfulness>=0.5`. |
| `before` | string | The page after this trace: the previous response's `older`. |

Returns `traces`, each with `id`, `name`, `started_at`, `duration_us`, `span_count`, `error_count`, `input_tokens`, `output_tokens`, `session_id`, `user_id` and `environment`, and `older`, the cursor for the next page or `null`.

## get_trace

Returns a trace and its spans, ordered by start. Each span has `id`, `parent_id`, `name`, `kind` (`generation`, `tool`, `agent`, `retrieval` or `span`), `status`, `model`, `input_tokens`, `output_tokens`, `offset_us` and `duration_us`, in microseconds from the trace's start.

| Parameter | Type | Description |
| --- | --- | --- |
| `trace` | string | Required. Trace id, 32 hex characters. |
| `limit` | integer | Spans to return, 1 to 1,000. Default 200. |
| `after` | string | Continue after this cursor: the previous response's `spans_next`. |

`spans_next` is `null` when every span has been returned.

## get_span

Returns one span in full: `input` and `output`, `attributes`, `events`, `links`, `resource`, `scope`, `status_message`, `input_truncated`, `output_truncated` and `redacted_count`.

| Parameter | Type | Description |
| --- | --- | --- |
| `trace` | string | Required. Trace id, 32 hex characters. |
| `span` | string | Required. Span id, 16 hex characters. |

`input` and `output` are `{"messages": [{"role", "parts"}]}` or `{"value": ...}`. See [Input and output](https://docs.divergentlabs.xyz/tracing/otlp.md#input-and-output).

## delete_trace

Deletes a trace, its spans and its scores. Spans sent for the same trace id in the next 24 hours are refused.

| Parameter | Type | Description |
| --- | --- | --- |
| `trace` | string | Required. Trace id, 32 hex characters. |

Returns `{"deleted": "<trace>"}`.

## score_trace

Sets this key's score of a name on a trace, or on one of its spans. Scoring the same name on the same trace and span again replaces the value and keeps the id.

| Parameter | Type | Description |
| --- | --- | --- |
| `trace` | string | Required. Trace id, 32 hex characters. |
| `name` | string | Required. 1 to 64 letters, digits, dots, dashes or underscores. |
| `value` | number, boolean or string | Required. A string is a category, up to 128 characters. |
| `span` | string | Score this span instead of the whole trace. |
| `comment` | string | A note, up to 2,000 characters. |

Returns the score: `id`, `trace_id`, `span_id`, `name`, `data_type`, `value`, `comment`, `source`, `author`, `created_at` and `updated_at`.

## delete_score

Deletes one score, whoever gave it.

| Parameter | Type | Description |
| --- | --- | --- |
| `trace` | string | Required. Trace id, 32 hex characters. |
| `score` | string | Required. Score id. |

Returns `{"deleted": "<score>"}`.

## list_scores

Lists the org's scores, by id.

| Parameter | Type | Description |
| --- | --- | --- |
| `name` | string | Only scores of this name. |
| `trace` | string | Only scores on this trace. |
| `limit` | integer | Number of scores, 1 to 200. Default 100. |
| `after` | string | The page after this cursor: the previous response's `next`. |

Returns `scores`, `next`, and `snapshot_seq`, the same on every page. To keep a copy of every score, read every page, then call `list_score_changes` with `after` set to `snapshot_seq`. See [Keep a copy of every score](https://docs.divergentlabs.xyz/tracing/guides/scores.md#keep-a-copy-of-every-score).

## list_score_changes

Returns the changes to the org's scores after a seq, oldest first.

| Parameter | Type | Description |
| --- | --- | --- |
| `after` | integer | Return changes after this seq. Default 0. |
| `limit` | integer | Number of changes, 1 to 1,000. Default 500. |

Returns `changes`, each with `seq`, `op` (`score_upserted`, `score_deleted`, `trace_deleted` or `trace_expired`), `trace_id`, `score_id`, `score` and `at`, and `next`, the seq to pass as `after` next. A seq older than 30 days is refused with `cursor_expired`.