Tracing MCP tools

The Divergent MCP server provides the operations of div traces, div trace, div score and div scores as tools. Setup is on that page. 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 the org’s traces, newest first.
get_trace	Return a trace and its spans, without their content.
get_span	Return one span in full.
delete_trace	Delete a trace, its spans and its scores.
score_trace	Set a score on a trace or one of its spans.
delete_score	Delete a score.
list_scores	List the org’s scores.
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.

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.

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.