MCP

The engine serves the Model Context Protocol at /v1/mcp, from the same process that stores your traces. Through the gateway, a coding agent can search spans, diagnose a failed session, compare two runs, ask how runs like this one ended, X-ray a model call and ask which step wrote a line of code, with a key you control.

Connect

claude mcp add --transport http traza https://api.trazadb.com/v1/mcp \
  --header "Authorization: Bearer $TRAZA_API_KEY"

Any client that speaks the Streamable HTTP transport connects the same way: one URL, POST only, a bearer header. Supported protocol revisions are 2025-11-25 and 2025-06-18.

The engine’s bundled stdio bridge (traza-server mcp --url …) speaks plain HTTP only and refuses an https:// URL, so it is for self-hosted servers; use the HTTP form above for Traza Cloud.

Keys

Use a read key. It reaches every read tool, scoped to your project.

Tool	Answers
describe_store	What is in here, and what may I ask about?
search_spans	Find spans that look like this
get_trace	This whole trace, in order
list_sessions, get_session	Which conversations ran, and what did one do?
diagnose_session	Why did this run fail?
top_failures, slowest_spans	What is breaking, and what is slow?
analyze_cost	Where did the tokens and the money go?
get_payload	The full prompt behind a reference
check_run_guard	May this run take its next step?
get_run_tape, compare_runs, recall_runs	What did this run do, where did it part from that one, has this been done before?
foresee_run	How have runs like this one ended, and what did the ones that succeeded do next?
list_live_runs, run_topology	Which runs are working now, and how did this run’s agents hand work around?
xray_step	What exactly did the model see at this step, and why did its cache break?
blame_line	Which agent step wrote this line of code, and why?
what_changed, find_behavior	What changed in this agent? Which runs did this — a pattern, or a named detector?
list_forks	Which branches of this run were tried, and how did each go?

The engine’s two write tools, record_annotation and promote_failures_to_dataset, exist only on a server started with their opt-in flags. Traza Cloud cells run without those flags, so a project here has the read tools only, whatever the key’s scope. check_run_guard reads a verdict; nothing over MCP can trip or reset a fuse, and there is no replay tool. The engine’s MCP guide documents every tool, resource and prompt.

Untrusted content

Stored span text is whatever your agents and their users sent, so the engine treats it as attacker-controlled. Tool results keep it inside blocks marked untrusted, it never reaches a tool description or an error message, and the server has no fetcher, no shell and no outbound network path to be talked into using. Results are bounded in tokens. Still, connect an agent only to projects whose contents it should read.