tracelane-mcp

@tracelanedev/mcp — Tracelane MCP 服务

只读 MCP 服务，可将 Tracelane 跟踪数据提供给任何兼容 MCP 的客户端，包括 Claude Desktop、Claude Code、Cursor，或任何使用 Model Context Protocol 的 Agent。

自 2026-09-07 起在 npm 上发布： npx @tracelanedev/mcp 会安装已发布的版本；下方的配置块可以直接使用。仍在自托管部分介绍如何从源代码运行。 同一次运行还会将 apps/mcp/server.json 提交到 MCP registry；该服务将在 io.github.tracelane/tracelane-mcp 名称下列出。

默认模式通过网关读取——使用仪表板所用的相同租户范围 /v1/* 路由，只需设置 TRACELANE_API_KEY 和 TRACELANE_GATEWAY_URL。这是 Cloud 租户路径，无需 ClickHouse 凭据。设置 CLICKHOUSE_URL 即可切换到自托管模式，改为直接读取 ClickHouse；详见自托管。

快速开始

Cloud（由 Tracelane 托管的租户）

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）、%APPDATA%\Claude\claude_desktop_config.json（Windows），或 Claude Code 项目根目录下的 .mcp.json：

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

不要设置 CLICKHOUSE_URL——不设置它即可选择网关模式。所有读取操作都会通过网关现有的租户范围路由进行，因此，如果密钥属于其他租户，或不具备 read 范围，工具会返回明确的错误，而不是空结果。

从克隆的仓库运行

将两个启动键替换为指向你克隆仓库的路径——所有 env 键保持不变：

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

先使用 pnpm install && pnpm --filter @tracelanedev/mcp build 构建。

此软件包内置 Streamable HTTP 传输（TRACELANE_MCP_TRANSPORT=http，见传输方式）——请自行运行。没有托管端点：https://mcp.tracelane.dev 无法解析，因此 url 风格的客户端配置没有可连接的地址。

自托管（ClickHouse）

设置 CLICKHOUSE_URL，即可直接读取 ClickHouse，而不是通过网关读取；适用于自托管或本地 Tracelane 技术栈：

{
  "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——系统会在此处验证 TRACELANE_API_KEY（/v1/auth/whoami），尽管跟踪数据是从 ClickHouse 读取的。

工具

工具	说明
list_traces	列出该租户的近期跟踪记录。参数：limit（默认值为 20）、model_filter、has_error
get_trace	获取某条跟踪记录的所有 span。参数：trace_id
get_span	获取某个 span 的完整详情，包括所有 LLM GenAI 属性。参数：span_id、trace_id——Cloud（网关）模式下必需（网关没有按 span ID 查询的路由；会从该跟踪记录的 span 列表中选出对应 span），自托管模式下可选
search_traces	在 span 名称和属性中进行全文搜索。参数：query（网关模式要求至少 4 个字符）、model_filter?、has_error?、limit。网关模式返回经过内容筛选的跟踪摘要；自托管模式返回每个 span 的匹配详情（matched_spans、first_match_*）
explain_guardrail_block	以易读的方式解释护栏信号。自托管模式：trace_id + span_id（记录的 span 上由检测层设置的 AFT 标志）。网关模式：二选一，correlation_id（来自拦截请求的 403 响应正文，适用于预检阶段拦截且没有跟踪记录的请求），或 trace_id + span_id（同样适用于 AFT 标志场景；由于 span 无论如何都会携带该标志，因此仍然可用）
list_evals	列出所有痛点和容错评估的 ID 及数量；数据来自构建时从 evals/ 打包的清单。参数：无
get_eval_result	读取特定评估的断言。需要有仓库检出副本才能获取源文件；如果没有，会明确说明。参数：eval_id
replay_trace	原样返回已记录的跟踪数据（按顺序排列的 span 及其 LLM/工具属性），用于离线逐步查看。**只读——不会重新执行任何模型或工具。**参数：trace_id、include_tool_calls?

在 Claude 中的示例用法

连接后，你可以询问 Claude：

"显示最近 5 条触发护栏拦截的跟踪记录，并解释触发了什么。"

"比较最近一小时内使用 claude-haiku-4-5 和 claude-sonnet-4-6 的跟踪记录延迟。"

"显示 eval 执行的断言。"

身份验证

通过 MCP 环境配置块传入 TRACELANE_API_KEY 环境变量。服务会根据 API 密钥解析租户——tenant_id 永远不会作为工具参数接受。

传输方式

传输方式	选择方式	适用场景
Stdio	默认	本地使用——Claude Desktop、Claude Code、Cursor。不会暴露网络。
Streamable HTTP	TRACELANE_MCP_TRANSPORT=http TRACELANE_MCP_PORT=8081	自行运行的远程部署。每个请求都必须携带 Authorization: Bearer <jwt-or-tlane-key>；网关会针对每个请求解析租户。我们不会为你运行托管端点。

安全不变量

• 只读。 不会注册任何写入工具——工具集就是上面列出的八项，全部仅用于读取。
• 租户隔离。 网关模式：每次读取都是限定租户范围的网关路由（crates/gateway/src/trace_reads.rs）——租户来自服务端的 Bearer 声明，本服务不会发送或看到租户 ID。自托管模式：每个 ClickHouse 查询都包含 WHERE tenant_id = {tenantId: String}（使用参数绑定，绝不通过字符串插值）。
• 两种模式下，tenant_id 都不会作为工具参数。 Stdio 模式会在启动时通过网关从 TRACELANE_API_KEY 解析一次租户；如果密钥被拒绝，则拒绝启动。HTTP 模式会针对每个请求从 Bearer 令牌解析租户，并通过 AsyncLocalStorage 绑定。
• 非 2xx 网关响应会作为工具错误返回，绝不会视为空结果。 密钥已撤销或租户错误、密钥缺少 read 作用域，或跟踪 ID 属于其他租户时，读取结果都会返回包含网关自身状态和消息的 isError: true，而不是 []。
• 文件系统不会接触 eval ID。 get_eval_result 会在随附清单中查找 ID 并使用清单中的路径，因此路径遍历字符串无法指定文件。
• 发送任何 Bearer 令牌前，都会对 TRACELANE_GATEWAY_URL 进行 SSRF 检查，两种模式均如此：开发环境以外仅允许 https、仅允许 tracelane.dev 主机，并拒绝私有网段、CGNAT 和 IMDS 地址范围。

运维人员须知： span 内容会按存储时的原样返回。请将提供给本服务的 API 密钥限制在你愿意将其 span 内容交给已连接模型的工作区。

自托管

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

MCP 服务没有发布容器镜像——ghcr.io/tracelane/mcp 不存在。请从源代码或 npm 包运行。

技术栈

• @modelcontextprotocol/sdk — 官方 MCP SDK（stdio + Streamable HTTP）
• @clickhouse/client — 使用参数绑定的 ClickHouse 查询
• TypeScript 5.5 严格模式，noUncheckedIndexedAccess: true
• 使用 Biome 进行 lint 和格式化

许可证

Apache 2.0 — 详见 LICENSE。