# trace-forge [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/mdfifty50-boop/trace-forge-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 174  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/trace-forge

## Description
Structured execution trace and span logging for AI agents

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "trace-forge": {
    "command": "npx",
    "args": ["-y","trace-forge-mcp"]
  }
}
```

## Documentation

## What trace-forge does

The trace-forge MCP server provides a write path for structured observability data generated during AI agent tasks. It records a top-level trace for a task, optional nested spans for logical work units, tool-call events, and decision events. A trace can be completed with an outcome and optional summary, after which the server reports totals such as duration, event count, span count, and tool-call count.

Decision records include the agent’s reasoning, alternatives considered, selected action, and a confidence value from 0.0 to 1.0. Tool-call records include the tool name, arguments, a result preview limited to 500 characters, duration, status, and optionally token usage. When token usage is supplied, the server calculates a cost estimate.

The project is designed for traceability of agent actions and decisions, including the EU AI Act Article 14 use case described in its documentation. It does not claim to replace legal or compliance review.

## How it works

A typical workflow begins with `trace_start`, which returns a trace identifier and start time. Use `trace_span` to create named units such as research or validation; a `parent_span_id` allows spans to form a hierarchy. During execution, record each tool invocation with `trace_tool_call` and decision points with `trace_decision`.

Call `trace_end` when the task finishes, using one of the supported outcomes: success, failure, partial, or timeout. The completed record can be inspected with `get_trace`, which returns the trace tree, events, tool calls, decisions, and computed totals. `search_traces` filters records by agent ID and/or status and returns recent matches with summary statistics.

The trace-forge MCP server also exposes `traces://recent` for the latest 20 traces and `traces://stats` for aggregate totals, average duration, and success rate.

## Setup and configuration

Run the server with npx:

```bash
npx trace-forge-mcp
```

For Claude Desktop, add an MCP server entry that uses `npx` as the command and `trace-forge-mcp` as its argument:

```json
{
  "mcpServers": {
    "trace-forge": {
      "command": "npx",
      "args": ["trace-forge-mcp"]
    }
  }
}
```

You can also clone the repository, install its npm dependencies, and start it with `node src/index.js`. No environment variables are documented for configuration.

## Tools and capabilities

The trace-forge MCP server exposes these tools:

- `trace_start` creates a trace for an agent and task.
- `trace_span` creates nested or top-level spans.
- `trace_tool_call` records tool arguments, result previews, timing, status, and optional token usage.
- `trace_decision` records reasoning, alternatives, the chosen action, and confidence.
- `trace_end` closes a trace and computes execution totals.
- `get_trace` returns a complete trace tree.
- `search_traces` filters traces by agent and status, with a configurable limit from 1 to 100.

## Limitations and notes

The documented tool interface requires the caller to provide the trace ID for subsequent events. Tool calls require a result preview of no more than 500 characters, a duration, and a status. The available tool-call statuses are success, error, and timeout; trace outcomes are success, failure, partial, and timeout. Cost estimation depends on providing a token count, and the documentation does not specify a pricing model or storage backend.

_Full upstream README: https://allmcps.com/mcp/trace-forge/readme_