Downtrace

@downtrace/mcp

⚠️ Not production ready. Downtrace is a closed free pilot: no plans, no billing and no SLA. The ingestion protocol is v0 and can still change between minor versions. Install it where a dependency that is still moving is acceptable.

Downtrace as tools a coding agent can discover and use: the queries and the operations, over MCP.

product.md is explicit that this is not an optional integration — «a product that could only be operated from the interface would fail half of its users» — and that reading is not enough: «a report exporter does not satisfy it: an agent must be able to operate the product».

Running it

{

"mcpServers": { "downtrace": { "command": "npx", "args": ["-y", "@downtrace/mcp"], "env": { "DOWNTRACE_URL": "https://your-downtrace", "DOWNTRACE_TOKEN": "an access credential of level operate" } } } }

DOWNTRACE_URL is required. DOWNTRACE_TOKEN is not: without it the server comes up read-only, every operation is still listed, and calling one says what credential it would need. That is more use than refusing to start.

The shared administration password is not the token for a project. This server sends its token as a Bearer token, and in that shape the password opens list_projects and read_credential and no tool about a project: those answer it a 403 with needs: "access credential", because a project's reads and operations need an access credential of that project.

The token is read from the environment and never from an argument: an argument ends up in a process list and in a shell history, and this one can close findings.

What it speaks

Standard input and output, JSON-RPC 2.0. Tools only — no resources, no prompts.

Each message is answered when its own work is done, not after the one before it: a ping is answered at once while a slow read is still waiting for the cloud, and two calls are answered in the order they finish, each carrying the id of its request. How many are in flight is up to the client; each call waits for the cloud for at most 30 seconds. When the input ends, the calls still in flight are answered before the server exits.

`notifications/cancelled` stops the call it names: the request to the cloud is aborted and the cancelled request gets no answer — none at all, even when its answer was ready but not yet written. A cancellation that names no request in flight does nothing. Cancelling an operation stops the waiting, not necessarily the operation: if its request had already reached the cloud, it may have been applied. An operation whose cancellation matters passes its own idempotencyKey: the retry with that key either applies it or answers with what the first one did.

MCP revisions `2025-11-25`, `2025-06-18` and `2024-11-05`, and the client's `initialize` chooses. A revision this server speaks is answered with that same one. Any other is answered with the newest one this server speaks that is not later than it; one earlier than all three, a value that is not a revision, or none at all, with 2025-11-25. So a client that asks for 2025-03-26 gets 2024-11-05: that revision obliges a server to accept JSON-RPC batches, which the next one withdrew, and this server does not implement it. A 2024-11-05 session gets exactly the messages it always got.

From `2025-06-18`, every tool carries its hints (annotations). A read says readOnlyHint: true. An operation says readOnlyHint: false and idempotentHint: false —without its key, repeating an operation is another operation— and destructiveHint: true when it can take back or overwrite what somebody decided: closing a finding, accepting a reference, annotating a finding (which can reopen it), resolving, ignoring or unignoring an error, a silence and its lifting. The ones that only add a record beside the others —a rating, an assessment, a note on an error, a regression, a capture request— say destructiveHint: false. No tool reaches beyond the cloud, so none is open-world. They are hints: what a credential may do is still decided by the cloud, by its level.

From `2025-06-18`, a result carries `structuredContent` beside its text: the JSON object the cloud answered, parsed as it came, so anything under fromService is still wrapped. There is no outputSchema, because declaring one obliges a server to keep to it and the shape belongs to the API. A refusal, or an answer that is not a JSON object, carries only its text.

In every revision, the schemas say what the API accepts. A closed set of values is an enum, an instant a date-time, the length of the errors list a whole number from 1 to 200, a page of a capture's requests a whole number from 1 to 100 from a place of 0 onwards, and a page of changes a whole number from 1 to 50 from a place of 0 onwards; identifiers are strings. The values of each enum are written here, because this package does not read the cloud's code, and an end-to-end walk compares them with the cloud's in both directions.

A failure is a result with isError, the HTTP status and the cloud's own sentence. There is no error code of this server's own. A credential refused for its level is told which: the cloud answers 403 with the level the credential has and the level the operation needs —or access credential, to the administration password at a tool about a project—, while a token that is not a usable credential —invented, expired or revoked— gets the 401, the same one for the three.

An answer cut short is a result with isError too: its status came, and then the connection dropped or the 30 seconds ran out before the whole body did. It says the status the cloud answered, that its answer was cut short, and what cut it. An operation's then says it may or may not have been applied, and names the idempotencyKey it was sent with, the one this server generated when the call passed none: called again with the same arguments and that key, it is not applied a second time.

No dependencies. The protocol a tools-only server needs is three methods, and it is written out here. See ADR 0078 for the argument and for the risk.

The tools

Named after the capability, not the route: an agent looks for "verify the recovery", not for GET /findings/{id}/verification.

Every operation carries an idempotency key, so a retry after a dropped connection is not a second operation. Each operation takes an optional idempotencyKey, and its description says when a key may be reused: the retry of the same operation after a failure or a dropped connection passes the same key, and the cloud answers it with the result of the first call; a new operation passes a different key or none, and without a key the server generates one. A key identifies one operation — the same note written twice on purpose needs two keys — and the cloud refuses a key that was already used for a different request. The three the product names as depending on a report — closing, assessing a hypothesis, accepting a reference — require the report's version, the one read_report gives: the operation is deci