tracelane-mcp

@tracelanedev/mcp — Tracelane MCP Server

Read-only MCP server exposing Tracelane trace data to any MCP-compatible client — Claude Desktop, Claude Code, Cursor, or any agent using the Model Context Protocol.

On npm since 2026-09-07: npx @tracelanedev/mcp installs the published version; the config blocks below work as written. From-source is still documented under self-hosting. The same run submits apps/mcp/server.json to the MCP registry; the name it will be listed under is io.github.tracelane/tracelane-mcp.

Default mode reads through the gateway — the same tenant-scoped /v1/* routes the dashboard uses — with just TRACELANE_API_KEY and TRACELANE_GATEWAY_URL. That is the Cloud-tenant path and needs no ClickHouse credentials. Set CLICKHOUSE_URL to switch to self-host mode, reading ClickHouse directly instead — see Self-hosting.

Quick start

Cloud (Tracelane-hosted tenant)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or .mcp.json at your project root for Claude Code:

{
  "mcpServers": {
    "tracelane": {
      "command": "npx",
      "args": ["@tracelanedev/mcp"],
      "env": {
        "TRACELANE_API_KEY": "tlane_YOUR_KEY",
        "TRACELANE_GATEWAY_URL": "https://gateway.tracelane.dev"
      }
    }
  }
}

No CLICKHOUSE_URL — its absence is what selects gateway mode. Every read goes through the gateway's existing tenant-scoped routes, so a key from another tenant, or one lacking the read scope, gets a clear tool error rather than an empty result.

Run from a clone

Swap the two launch keys for a path into your clone — every env key is unchanged:

"command": "node",
"args": ["/path/to/tracelane/apps/mcp/dist/index.js"]

Build it first with pnpm install && pnpm --filter @tracelanedev/mcp build.

The Streamable HTTP transport ships in this package (TRACELANE_MCP_TRANSPORT=http, see Transports) — run it yourself. There is no hosted endpoint: https://mcp.tracelane.dev does not resolve, so a url-style client entry has nothing to connect to.

Self-host (ClickHouse)

Set CLICKHOUSE_URL to read ClickHouse directly instead of the gateway — for a self-hosted or local Tracelane stack:

{
  "mcpServers": {
    "tracelane": {
      "command": "npx",
      "args": ["@tracelanedev/mcp"],
      "env": {
        "TRACELANE_API_KEY": "tlane_YOUR_KEY",
        "TRACELANE_GATEWAY_URL": "https://gateway.tracelane.dev",
        "CLICKHOUSE_URL": "http://localhost:8123",
        "CLICKHOUSE_USER": "default",
        "CLICKHOUSE_PASSWORD": "…"
      }
    }
  }
}

TRACELANE_GATEWAY_URL is still needed in self-host mode — it is where TRACELANE_API_KEY is validated (/v1/auth/whoami) even though trace reads go to ClickHouse instead.

Tools

Tool	Description
list_traces	List recent traces for the tenant. Params: limit (default 20), model_filter, has_error
get_trace	Get all spans for a trace. Params: trace_id
get_span	Get full details for a span including all LLM GenAI attributes. Params: span_id, trace_id — required in Cloud (gateway) mode (no span-by-id gateway route; the span is picked out of the trace's span list), optional in self-host mode
search_traces	Free-text search across span names and attributes. Params: query (gateway mode requires ≥4 chars), model_filter?, has_error?, limit. Gateway mode returns content-filtered trace summaries; self-host mode returns per-span match detail (matched_spans, first_match_*)
explain_guardrail_block	Human-readable explanation of a guardrail signal. Self-host mode: trace_id + span_id (a detection-layer AFT flag on a recorded span). Gateway mode: EITHER correlation_id (from a block's 403 body, for a request blocked pre-flight with no trace) OR trace_id + span_id (same AFT-flag case, still available since spans carry the flag either way)
list_evals	List every pain-point + fault-tolerance eval id and count, read from the manifest bundled at build time from evals/. Params: none
get_eval_result	Read a specific eval's assertions. Needs a repo checkout for the source; says so when there is none. Params: eval_id
replay_trace	Return a 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. Params: trace_id, include_tool_calls?

Example usage in Claude

Once connected, you can ask Claude:

"Show me the last 5 traces that had a guardrail block, and explain what fired."

"Compare the latency of traces using claude-haiku-4-5 vs claude-sonnet-4-6 in the last hour."

"Show me the assertions that eval makes."

Auth

TRACELANE_API_KEY environment variable passed via the MCP env block. The server resolves the tenant from the API key — tenant_id is never accepted as a tool argument.

Transports

Transport	How to select it	When to use
Stdio	default	Local use — Claude Desktop, Claude Code, Cursor. Zero network exposure.
Streamable HTTP	TRACELANE_MCP_TRANSPORT=http TRACELANE_MCP_PORT=8081	Self-run remote deployments. Every request must carry Authorization: Bearer <jwt-or-tlane-key>; the tenant is resolved per request through the gateway. No hosted endpoint is operated for you.

Security invariants

• Read-only. No write tools are registered — the tool surface is the eight listed above, all of which only read.
• Tenant isolation. Gateway mode: every read is a tenant-scoped gateway route (crates/gateway/src/trace_reads.rs) — the tenant comes from the bearer's claims server-side, this server never sends or sees a tenant id. Self-host mode: every ClickHouse query includes WHERE tenant_id = {tenantId: String} (parameter-bound, never string-interpolated).
• tenant_id is never a tool parameter in either mode. Stdio resolves it once at startup from TRACELANE_API_KEY via the gateway and refuses to start if the key is rejected; HTTP resolves it per request from the bearer token and binds it through AsyncLocalStorage.
• A non-2xx gateway response is a tool error, never an empty result. A revoked or wrong-tenant key, a key missing the read scope, or another tenant's trace id all read back as isError: true carrying the gateway's own status and message — not [].
• No eval id reaches the filesystem. get_eval_result looks the id up in the bundled manifest and uses the manifest's path, so a traversal string cannot name a file.
• TRACELANE_GATEWAY_URL is SSRF-checked before any bearer is sent to it, in both modes: https-only outside development, tracelane.dev hosts only, private/CGNAT/IMDS ranges refused.

Operator note: span content is returned as stored. Scope the API key you give this server to workspaces whose spans you are comfortable handing to the connected model.

Self-hosting

# From source, against your own stack
pnpm dev:mcp

No container image is published for the MCP server — ghcr.io/tracelane/mcp does not exist. Run it from source or from the npm package.

Stack

• @modelcontextprotocol/sdk — official MCP SDK (stdio + Streamable HTTP)
• @clickhouse/client — parameter-bound ClickHouse queries
• TypeScript 5.5 strict, noUncheckedIndexedAccess: true
• Biome for lint + format

License

Apache 2.0 — see LICENSE.