Tracelane MCP server for AI IDE clients

The Tracelane MCP server exposes your agent traces and guardrail verdicts as Model Context Protocol tools. Use it to give Claude (or any MCP-compatible LLM) live access to your production traces during debugging. Read-only by design. The server can never modify traces, change configuration, or access another tenant’s data. By default the server reads through the gateway — the same tenant-scoped /v1/* routes the dashboard uses — with just an API key and the gateway URL, no ClickHouse credentials. Set CLICKHOUSE_URL to read ClickHouse directly instead, for a self-hosted or local Tracelane stack.

Run it

Build it from a clone:

git clone https://github.com/tracelane/tracelane && cd tracelane
pnpm install && pnpm --filter @tracelanedev/mcp build

Then start it against your Tracelane Cloud workspace. The gateway URL validates TRACELANE_API_KEY and — with no CLICKHOUSE_URL set — is also where every trace read goes:

TRACELANE_API_KEY=tlane_... \
TRACELANE_GATEWAY_URL=https://gateway.tracelane.dev \
node apps/mcp/dist/index.js

Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tracelane": {
      "command": "node",
      "args": ["/path/to/tracelane/apps/mcp/dist/index.js"],
      "env": {
        "TRACELANE_API_KEY": "tlane_...",
        "TRACELANE_GATEWAY_URL": "https://gateway.tracelane.dev"
      }
    }
  }
}

Restart Claude Desktop. You should see “tracelane” in the MCP tools list.

Configure Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "tracelane": {
      "command": "node",
      "args": ["/path/to/tracelane/apps/mcp/dist/index.js"],
      "env": {
        "TRACELANE_API_KEY": "tlane_...",
        "TRACELANE_GATEWAY_URL": "https://gateway.tracelane.dev"
      }
    }
  }
}

Self-host (ClickHouse) instead

Set CLICKHOUSE_URL to read ClickHouse directly rather than through the gateway — for a self-hosted or local Tracelane stack. TRACELANE_GATEWAY_URL is still needed; it is where TRACELANE_API_KEY is validated (/v1/auth/whoami) even though trace reads go to ClickHouse instead:

{
  "mcpServers": {
    "tracelane": {
      "command": "node",
      "args": ["/path/to/tracelane/apps/mcp/dist/index.js"],
      "env": {
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "...",
        "TRACELANE_API_KEY": "tlane_...",
        "TRACELANE_GATEWAY_URL": "http://localhost:8080"
      }
    }
  }
}

Available tools

`list_traces`

mcp.tracelane.list_traces({
  limit: 20,                            // optional, 1-100, default 20
  model_filter: "claude-sonnet-4-6",    // optional, exact model name
  has_error: true,                      // optional, traces with >=1 error span
})

Returns: array of trace summaries (trace_id, root_name, start_time, duration_us, span_count, error_count, intervention, model).

`get_trace`

mcp.tracelane.get_trace({ trace_id: "uuid" })

Returns: full span tree with all OTel GenAI attributes, predictive layer annotations, token counts, and latency breakdown.

`get_span`

mcp.tracelane.get_span({ trace_id: "uuid", span_id: "uuid" })

trace_id is required when reading through the gateway (Cloud mode) — there is no span-by-id gateway route, so the span is located via the trace’s span list. Self-host (ClickHouse) mode accepts span_id alone. Returns: single span with all attributes and predictive verdict detail. Input and output content appears only if content capture is enabled for the workspace (see Security); it is off by default.

`search_traces`

mcp.tracelane.search_traces({
  query: "tool_call browserbase stuck-loop",
  model_filter: "claude-sonnet-4-6",  // optional
  has_error: true,                     // optional
  limit: 10,                           // optional, 1-50, default 10
})

Free-text search across span names and attribute JSON. Gateway mode rejects a query shorter than 4 characters. There is no time-window filter on this tool today.

`explain_guardrail_block`

// Self-host (ClickHouse) mode — a detection-layer (AFT) flag on a recorded span:
mcp.tracelane.explain_guardrail_block({ trace_id: "uuid", span_id: "uuid" })

// Gateway (Cloud) mode also accepts a correlation_id — the id from a guardrail
// block's 403 response body, for a request blocked pre-flight (no trace exists
// for it, since the request never dispatched):
mcp.tracelane.explain_guardrail_block({ correlation_id: "01ABC..." })

Returns a structured explanation: which AFT rule fired, the evidence, the intervention taken, and how to resolve. Example output:

R4_trifecta — lethal-trifecta taint sequence

Evidence:
  - Untrusted input entered at span 3 (user message)
  - Private data accessed at span 7 (read_file tool)
  - External write attempted at span 9 (send_email tool)

Intervention: flagged — detection is observe-first by default, so the
request was forwarded and the finding recorded on the trace.

Resolution: review span 7–9 for unintended data exfiltration.

`list_evals`

mcp.tracelane.list_evals()

Takes no parameters — it always returns the full bundled eval manifest (id, suite, and count for every pain-point and fault-tolerance eval), not a suite-filtered subset.

`get_eval_result`

mcp.tracelane.get_eval_result({ eval_id: "onboarding-latency" })

Returns the latest result for a specific eval, including assertion details and the last run timestamp.

`replay_trace`

mcp.tracelane.replay_trace({ trace_id: "uuid", include_tool_calls: true })

Returns the recorded trace as-is (ordered spans with LLM/tool attributes) for offline step-through. Read-only — it does not re-execute any model or tool. Live shadow / cross-model re-execution is a gateway capability, not exposed via MCP.

Transport

Mode	When to use
Stdio (default)	Claude Desktop, Cursor, local development
Streamable HTTP	Remote deployments, CI/CD pipelines, Composio

Start in HTTP mode:

TRACELANE_MCP_TRANSPORT=http \
TRACELANE_MCP_PORT=3100 \
node apps/mcp/dist/index.js

Auth

V1: TRACELANE_API_KEY env var — the tlane_* key is validated against the gateway’s /v1/auth/whoami. In gateway (Cloud) mode the key also authenticates every subsequent trace read; the gateway resolves tenant_id from the key’s claims and scopes every route to it server-side. In self-host mode, the resolved tenant_id scopes every ClickHouse query this server issues. V2: OAuth 2.1 PKCE — tenant_id extracted from the JWT claim only, never from tool arguments.

Security invariants

Read-only: no write tools are exposed — enforced at the @modelcontextprotocol/sdk handler level.
Gateway mode: every read is a tenant-scoped gateway route; this server never sends or sees a tenant id. Self-host mode: every ClickHouse query includes WHERE tenant_id = {tenantId: String} (parameter-bound).
tenant_id from env/JWT only — MCP tool arguments cannot override it in either mode.
A non-2xx gateway response is a tool error, never an empty result — a revoked key, a key missing the read scope, or another tenant’s trace id all surface the gateway’s own status and message.
No raw SQL in tool arguments — all filters are parsed into typed query parameters.

Get started

SDKs

Integrations

Concepts

Features

Tools

Audit & compliance

Operations

Migrations

Comparisons

Tracelane MCP server for AI IDE clients

Run it

Configure Claude Desktop

Configure Claude Code

Self-host (ClickHouse) instead

Available tools

`list_traces`

`get_trace`

`get_span`

`search_traces`

`explain_guardrail_block`

`list_evals`

`get_eval_result`

`replay_trace`

Transport

Auth

Security invariants

​Run it

​Configure Claude Desktop

​Configure Claude Code

​Self-host (ClickHouse) instead

​Available tools

​list_traces

​get_trace

​get_span

​search_traces

​explain_guardrail_block

​list_evals

​get_eval_result

​replay_trace

​Transport

​Auth

​Security invariants

​Related

Run it

Configure Claude Desktop

Configure Claude Code

Self-host (ClickHouse) instead

Available tools

`list_traces`

`get_trace`

`get_span`

`search_traces`

`explain_guardrail_block`

`list_evals`

`get_eval_result`

`replay_trace`

Transport

Auth

Security invariants

Related