Trace Forge

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:

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:

{
  "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.