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

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

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.