Get started

API / Cookbook / 02

Let an agent search its past runs

Agents are first-class users of Recurz. Give one the Tracez MCP server and it can answer “how did we fix this last time?” from your own transcripts instead of guessing.

MCPLive

One question, answered from history
actor you: You
actor agent: Your agent
actor mcp: Tracez MCP
you -> agent: How did we fix the flaky auth test?
agent -> mcp: initialize
mcp --> agent: tools capability, server info
agent -> mcp: tools/list
mcp --> agent: Tracez's tools with input schemas
agent -> mcp: tools/call list_sessions {q: "flaky auth"}
mcp --> agent: data, next_cursor, has_more
loop until it has enough
agent -> mcp: tools/call list_turns {session_id, cursor}
mcp --> agent: a page of turns
end
agent --> you: The answer, citing the session

Steps

  1. Add the server to your client

    Any MCP client that supports remote HTTP servers needs two things: the URL and an Authorization header with your account token. In a project's .mcp.json for Claude Code that looks like this:

    {
  "mcpServers": {
    "tracez": {
      "type": "http",
      "url": "https://api.recurz.ai/tracez/v1/mcp",
      "headers": { "Authorization": "Bearer ${RECURZ_TOKEN}" }
    }
  }
}

  2. Search

    list_sessions matches q against session titles, native session ids and turn text, 50 sessions a page.

    {"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"list_sessions","arguments":{"q":"flaky auth"}}}

  3. Read

    Page through a session's turns with the next_cursor you got back. Long strings are cut at max_chars and pages stop near max_bytes; get_turn reads one turn whole.

    {"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"list_turns","arguments":{"session_id":"SESSION_ID"}}}

  4. Read the result

    Every tool returns its result in structuredContent, plus a JSON copy as text for clients that only read text. Lists page the same way everywhere. A refusal sets isError and carries the platform's error shape.

    {"data":[…],
 "next_cursor":"1873",
 "has_more":true}

An account token can call every tool, including delete_session and redact_session. If your client can allow-list tools, give the agent only the read tools it needs.