Hartrace

What is Hartrace?

Hartrace is an MCP server for analyzing HTTP traffic captures (HAR files). Its distinguishing feature is value provenance tracing: given any token, cookie, ID, or payload field, it reconstructs where the value was produced (which response set it) and where it was consumed (which later requests sent it), as a compact timeline. It is built so an AI agent can answer questions about a capture without reading the raw JSON into its context window. All tools return small, structured results with hard size caps, keeping analysis cheap regardless of capture size.

How to use Hartrace?

Install with pipx install hartrace, uvx hartrace, or pip install hartrace. Add it to your MCP client’s configuration (e.g., claude_desktop_config.json for Claude Desktop, .cursor/mcp.json for Cursor, or .vscode/mcp.json for VS Code). Then interact naturally: “Load ~/captures/login.har and tell me where the CSRF token comes from.” Hartrace exposes 19 tools for loading, inspection, search, provenance, and comparison. Loaded captures are referred to by the name returned from load_har.

Key features of Hartrace

• Provenance tracing (trace_value, trace_header) — follows any value across responses → requests, reporting JSON paths for body fields.
• Search toolkit — full regex search across URLs, headers, and request/response bodies; header, URL, endpoint, and query-parameter extraction.
• Inspection — per-request/response retrieval with base64 + gzip/deflate decoding, nested-JSON unwrapping, and size caps.
• Lifecycle maps — cookie_map and token_map summarize how cookies and high-entropy secrets flow through a session.
• Diffing — compare two captures by (method, url, ordinal) so repeated calls to the same endpoint align.
• Safe by construction — pagination with server-clamped limits, secrets redacted in inspection output, no exceptions across the tool boundary.

Use cases of Hartrace

• Trace the origin of an auth token or CSRF token through a multi‑request login flow.
• Find all requests that reuse a given session cookie or header value.
• Diff two HAR captures (e.g., before and after a deployment) to see what changed.
• Extract and inspect a specific request/response body without loading the entire raw JSON.
• Analyze how high‑entropy secrets propagate across a session using the token map.

FAQ from Hartrace

How does provenance tracing work?

On first trace, Hartrace builds a correlation index over the capture (cached for subsequent calls). It separates hits into set_by (responses that produced the value) and used_in (later requests that sent it), with JSON paths where applicable. Values shorter than four characters are refused.

What are the runtime requirements?

Python 3.10+ and the fastmcp package. No other dependencies are required.

How are outputs bounded to keep token usage predictable?

List and search tools paginate with limit/offset (clamped server‑side). Response bodies are capped by max_chars. Captures larger than 500 MB or 50,000 entries are rejected. All tools return structured error messages instead of raising exceptions.

Can I load a capture from a URL?

Yes, via the load_har_url tool. It guards against SSRF by refusing non‑http(s) schemes and any host resolving to private, loopback, link‑local, reserved, or multicast addresses, and enforces a download size cap.

How is sensitive data handled?

Inspection tools redact header values listed in sensitive_headers (configurable via config.json, e.g., authorization, cookie, set-cookie) when redact_sensitive_headers is set to true. High‑entropy opaque strings are always redacted using a Shannon‑entropy heuristic. find_header intentionally returns raw values so they can be traced with trace_value.