Skip to content
Trazum

Agent integrations

Documentation index · Setup · MCP reference · HTTP API

Trazum separates the harness that executes an agent, the model/provider that serves requests, and the payment mode that determines the invoice. Use the same analysis and plan documents across integrations. A successful MCP connection does not mean that Trazum can import that client's sessions or intercept its requests.

Choose an interface#

InterfaceUse it forBoundary
CLIRead authorized files, generate reports and plans, run CI checksFiles and commands run with the caller's permissions
MCPInspect costs, propose savings, verify plans and analyze task efficiencyTools receive text; no filesystem, network or model calls
Local HTTPImport native usage, check costs, plan and verify savingsExplicit text inputs; server catalogue; no spending reservation
GatewayApply policy to calls explicitly routed through itProcess-local accounting; external calls remain unseen
Agent skillTeach an agent which interface and evidence to useInstructions are not enforcement or spending authorization

Start with the setup instructions. For MCP, inspect tools/list on the running server before using a tool. Local development may include tools not yet available in an older npm release.

Install the MCP server in a client#

Every line below starts @trazum/mcp at the exact version the repository is at, and none asks for a marketplace account. The table and the snippets under it are written by node scripts/install-snippets.mjs --write from the version in packages/mcp/package.json, and packages/core/test/install-snippets.test.js holds each of them to that package name and that version. The same records draw the MCP section of the site's download page.

The server answers when a client asks it. It does not sit in front of the client's model calls, and it cannot see a request the client never sent it.

ClientWhereWhat to run or paste
Claude Codea terminalclaude mcp add trazum -- npx -y @trazum/mcp@3.0.1
Claude Desktop, one-click bundledownload the file, then open it with Claude Desktopthe address under "Claude Desktop, one-click bundle" below
Claude Desktop, JSONclaude_desktop_config.jsonthe snippet under "Claude Desktop, JSON" below
Cursor.cursor/mcp.jsonthe snippet under "Cursor" below
VS Code.vscode/mcp.jsonthe snippet under "VS Code" below
Codex, commanda terminalcodex mcp add trazum -- npx -y @trazum/mcp@3.0.1
Codex, TOML~/.codex/config.tomlthe snippet under "Codex, TOML" below
Gemini CLIa terminal; the version is the one gemini-extension.json namesgemini extensions install https://github.com/Davmunrey/Trazum

Claude Desktop, one-click bundle#

Where: download the file, then open it with Claude Desktop.

https://github.com/Davmunrey/Trazum/releases/download/v3.0.1/trazum-mcp-3.0.1.mcpb

Claude Desktop, JSON#

Where: claude_desktop_config.json.

{
  "mcpServers": {
    "trazum": {
      "command": "npx",
      "args": ["-y", "@trazum/mcp@3.0.1"]
    }
  }
}

Cursor#

Where: .cursor/mcp.json.

{
  "mcpServers": {
    "trazum": {
      "command": "npx",
      "args": ["-y", "@trazum/mcp@3.0.1"]
    }
  }
}

VS Code#

Where: .vscode/mcp.json.

{
  "servers": {
    "trazum": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@trazum/mcp@3.0.1"]
    }
  }
}

Codex, TOML#

Where: ~/.codex/config.toml.

[mcp_servers.trazum]
command = "npx"
args = ["-y", "@trazum/mcp@3.0.1"]

The Gemini CLI line installs gemini-extension.json from the repository's default branch, and that file names the server's version. The .mcpb bundle is attached to each release after npm serves the packages; if the address above is not there yet, the release page lists what the release carries.

Native import versus generic access#

The capabilities endpoint reports native import support independently from CLI, MCP and HTTP access. Claude Code, Codex and (since 2.7.0) Gemini CLI have native adapters; other clients can supply the normalized usage-log format. Do not treat Cursor or another MCP client's transcripts as supported simply because that client can call Trazum tools.

With the CLI, use explicit authorized paths with from-claude-code, from-codex or from-gemini-cli; trazum bill with no path reads the three agents' own session folders and names each one first. With MCP, call import_usage with explicit format (claude-code, codex or gemini-cli), session text and an optional approved label. The server never opens a path and never derives labels from working directories. Native adapter output excludes prompts, tool responses and paths, but retains session IDs. Keep raw transcripts out of model context where the host can pass them directly to the local tool.

The HTTP /usage/import route accepts the same format, text and optional label (maximum 200 characters). Its whole request and complete response each have a 1,000,000-byte UTF-8 cap. This route is available since 2.6.0; discover it through the running server's OpenAPI document.

The model ID comes from the source, not the harness name. Unknown models stay unpriced unless the user supplies a price card. Recorded token usage priced at catalogue rates is an API-equivalent estimate. A subscription, discounted invoice or provider credit requires separate evidence.

Diagnose, propose, verify#

trazum bill usage.jsonl --receipt
trazum plan usage.jsonl --json -o plan.json
trazum verify plan.json --against later.jsonl --json

For native transcripts, first call MCP import_usage and pass its returned log to profile_usage or plan_savings. A transcript passed to them directly is refused by name, with the import_usage call that converts it, rather than read as a log whose every line is unreadable. Preserve its diagnostics alongside later reports: empty output is not zero usage, conversion cannot establish source completeness, and separate imports do not share deduplication state. Do not concatenate overlapping imports. CLI normalization remains an alternative. For already normalized JSONL, use profile_usage, plan_savings, and verify_savings directly. HTTP equivalents are POST /savings/plan and POST /savings/verify, using the server catalogue and a shared 1,000,000-byte request limit. Native HTTP import returns the same normalized log; preserve its diagnostics too. A verify request must fit both the log and serialized plan inside that cap. Save the plan field from plan_savings as the document; the surrounding response holds additional evidence. Pass JSONL contents and serialized plan text to MCP, never file paths. The same plan can be opened in the dashboard.

Keep priced/unpriced coverage, the observed period, pricing provenance and assumptions with the result. Verification distinguishes arrived, not-arrived, and cannot-tell. A workload disappearing from a log is not evidence of savings. A cheaper model still needs a quality evaluation.

See the agent workflow reference for budget checks, unknown results, paid calls and gateway limitations.

Review efficiency across a task#

The task workflow, available since 2.6.0, groups explicit Claude Code and Codex sources, records a caller-supplied acceptance criterion and outcome, and reports repeated calls with matching recorded results. MCP analyze_task returns report and a fixed optional policy; compare_tasks compares saved reports. The policy is null without actionable repetition evidence. Discover their schemas with tools/list. Older servers may not expose them.

Task analysis reads tool content in memory to detect repetition. Reports omit raw tool content, paths and session IDs, retaining source/line references and non-cryptographic reuse checks. Explicit task metadata remains in the report. This is a separate workflow from usage-only native import.

Repeated calls can be necessary validation. Outcomes and policy application are explicit declarations, not independently verified facts. Keep incomplete coverage, inconclusive comparisons and quality regressions visible. For a reviewed policy, the CLI can append or revert its exact managed block in an explicit existing instruction file; MCP does not edit files or run the task.

Evaluate the integration#

npm run build
npm run test:agents

The evaluation launches the actual CLI and MCP stdio server with synthetic logs. It exchanges plans in both directions, compares deterministic results, checks that vanished workloads remain unknown, and refuses to turn a missing budget into spending permission. It makes no paid calls and uses no customer transcripts. This tests interface behavior, not an LLM's ability to follow the skill or preserve task quality.

The evaluation approach takes inspiration from ECC's eval-harness and verification-loop: define observable outcomes and run regression checks. No external hooks, agent pack, executable code or global configuration are installed. The Broch library was reviewed as a discovery source; its rankings are not a dependency or a security assessment.