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.

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.1 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, and safe retries. It does not sandbox trusted Python handlers or provide distributed durability, live remote replay, or proof of semantic equivalence.

Licensed under the MIT License.