Tracelane Mcp

io.github.tracelanev0.4.0更新于 Oct 9, 2026

Read-only, tenant-scoped access to Tracelane agent traces and guardrail verdicts

已验证STDIO仅桌面AI & ML Security & Monitoring Data & Analytics

概览

AI 生成的概览

以只读方式通过 MCP 访问 Tracelane 智能体追踪与护栏判定，让助手列出、搜索、查看并回放追踪记录。

功能: 提供八个只读工具访问 Tracelane 追踪数据：list_traces、get_trace、get_span、search_traces、explain_guardrail_block、list_evals、get_eval_result 和 replay_trace。可按模型和错误条件列出近期追踪、获取某条追踪的全部 span、查看某个 span 的完整 LLM GenAI 属性、在 span 名称与属性中做全文搜索，并解释护栏拦截原因。replay_trace 按原样返回已记录的追踪以供离线逐步查看，不会重新执行任何模型或工具。
适用场景: 适合调试或审查智能体运行：查找触发护栏拦截的追踪、比较不同模型的延迟、检查 span 级 LLM 属性，或阅读评估断言。适用于已将追踪存储在 Tracelane Cloud 或自建 Tracelane 栈的团队。
运行要求: 通过 npx @tracelanedev/mcp 以 stdio 在本地运行（需要 Node.js）。需要 TRACELANE_API_KEY 和 TRACELANE_GATEWAY_URL；非开发环境下网关地址必须为 https 且属于 tracelane.dev 主机。自建模式还需 CLICKHOUSE_URL、CLICKHOUSE_USER、CLICKHOUSE_PASSWORD 和 CLICKHOUSE_DB。get_eval_result 需要本地代码仓库检出。没有托管端点。

安装前请注意

需要密钥 TRACELANE_API_KEY，自建模式下还需要 CLICKHOUSE_PASSWORD。span 内容按存储原样返回，因此应把 API 密钥限定在可安全交给所连接模型的工作区。服务器为只读且按租户隔离，tenant_id 从不作为工具参数。网关返回非 2xx 时会作为工具错误呈现，而不是空结果。

安装

在 SourceWeft 中

打开控制台中的 Tracelane Mcp，将其添加到工作区。
为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照仓库中的启动说明。

README

`@tracelanedev/mcp` — Tracelane MCP Server

[license]

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:

json

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

{  "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:

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:

json

{  "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": "…"      }    }  }}

{  "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

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.

来源：apps/mcp/README.md，提交 6c65a11

工具

工具元数据尚未被收录。

版本历史

v0.4.0最新Oct 9, 2026