Trace2MCP

Teach once. Run forever.

Trace2MCP compiles a successful AI-agent tool-call trace into a deterministic, inspectable, MCP-ready workflow.

An agent can discover a useful procedure once. Trace2MCP then validates the trace, infers data dependencies, deduplicates safe reads, builds a directed acyclic graph (DAG), and identifies work that can run concurrently.

Install

pip install trace2mcp

To run generated MCP servers, install the optional MCP dependency:

pip install "trace2mcp[mcp]"

Python 3.10 or newer is required.

HOL Guard can optionally add a second runtime-policy decision before every managed handler call. Install it in an isolated environment and opt in explicitly:

pipx install hol-guard==2.2.125

$env:TRACE2MCP_HOL_GUARD_EXECUTABLE = (Get-Command hol-guard).Source

It remains disabled when that variable is unset. When enabled, an unavailable guard, error, timeout, malformed response, unknown action, denial, or review requirement prevents handler execution. HOL Guard is not bundled because its current MCP requirement conflicts with the MCP v2 extra used by Trace2MCP-generated servers.

Try it

trace2mcp demo
trace2mcp inspect trace.json
trace2mcp compile trace.json --out build/my-workflow
trace2mcp verify build/my-workflow/workflow.json
trace2mcp replay build/my-workflow/workflow.json --frozen
trace2mcp benchmark trace.json --repetitions 3

trace2mcp demo runs the complete offline path: teach, compile, verify, frozen replay, and a visible safety-gate example. It uses no model, API key, or network.

Or use the Python API:

from trace2mcp import compile_trace, load_trace

trace = load_trace("trace.json")
workflow = compile_trace(trace, allow_side_effects=False)

print(workflow.to_dict())

The compile command produces a portable workflow.json, inert handler stubs, unreviewed contract candidates, and a minimal MCP server skeleton. You provide and review the real implementations and contracts; observed trace outputs are never converted into executable code.

Why compile traces?

• Lower orchestration overhead: reuse a discovered procedure instead of planning the same tool path on every run.
• Dependency-aware execution: independent read-only calls can run in parallel.
• Fail-closed safety: unknown and destructive operations are denied; consequential operations need a reviewed contract and explicit approval.
• Auditability: tool calls, references, dependencies, and scheduling remain visible as portable JSON.
• Provider-neutral design: the core compiler does not require a model or an API key.

Live demo

Use the free, browser-only Trace2MCP interactive demo or visit the Hugging Face Space.

The included demo uses synthetic outputs and recorded durations to explain the scheduler. Its speedup is educational, not a production performance claim.

Safety

Trace2MCP is an alpha research tool. Version 0.2.2 routes supported direct and nested capability calls through one dispatcher, verifies structure and integrity, enforces reviewed generated contracts and schemas, and runs local handlers with bounded concurrency, timeouts, safe retries, and an optional fail-closed runtime guard. It does not sandbox trusted Python handlers or provide distributed durability, live remote replay, or proof of semantic equivalence.

Licensed under the MIT License.