tracelane-mcp

@tracelanedev/mcp — Tracelane MCP サーバー

Tracelane のトレースデータを公開する読み取り専用 MCP サーバーです。Claude Desktop、Claude Code、Cursor、または Model Context Protocol を使用する任意のエージェントなど、MCP 互換のクライアントから利用できます。

2026-09-07 から npm で公開中： npx @tracelanedev/mcp で公開済みのバージョンをインストールできます。以下の設定ブロックはそのまま使用できます。ソースからの実行方法は、引き続きセルフホストに記載しています。 同じ実行で apps/mcp/server.json が MCP レジストリに送信されます。登録名は io.github.tracelane/tracelane-mcp です。

デフォルトモードでは、ゲートウェイ経由で読み込みます。ダッシュボードが使用するものと同じ、テナントスコープの /v1/* ルートを使い、必要なのは TRACELANE_API_KEY と TRACELANE_GATEWAY_URL のみです。これは Cloud テナント向けの方法で、ClickHouse の認証情報は不要です。代わりに ClickHouse を直接読み込むセルフホストモードに切り替えるには、CLICKHOUSE_URL を設定してください。詳しくはセルフホストを参照してください。

クイックスタート

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 スコープがないキーを使った場合は、空の結果ではなく、明確なツールエラーが返されます。

クローンから実行する

2 つの起動キーをクローン内のパスに置き換えます。すべての 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）

セルフホストまたはローカルの Tracelane スタックで、ゲートウェイの代わりに ClickHouse を直接読み込むには、CLICKHOUSE_URL を設定します。

{
  "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 は必要です。トレースの読み込み先は ClickHouse ですが、TRACELANE_API_KEY の検証先（/v1/auth/whoami）として使用されます。

ツール

ツール	説明
list_traces	テナントの最近のトレースを一覧表示します。パラメーター：limit（デフォルトは 20）、model_filter、has_error
get_trace	トレースのすべてのスパンを取得します。パラメーター：trace_id
get_span	すべての LLM GenAI 属性を含む、スパンの詳細を取得します。パラメーター：span_id、trace_id — Cloud（ゲートウェイ）モードでは必須（スパン ID で取得するゲートウェイルートがないため、トレースのスパン一覧からスパンを選び出します）。セルフホストモードでは省略可能です
search_traces	スパン名と属性を対象に全文検索します。パラメーター：query（ゲートウェイモードでは 4 文字以上が必要）、model_filter?、has_error?、limit。ゲートウェイモードではコンテンツフィルター済みのトレース概要を返します。セルフホストモードではスパンごとの一致詳細（matched_spans、first_match_*）を返します
explain_guardrail_block	ガードレールシグナルを人が読みやすい形で説明します。セルフホストモード：trace_id と span_id（記録済みスパン上の検出レイヤー AFT フラグ）。ゲートウェイモードでは、次のいずれかを指定します。トレースがなくリクエストがフライト前にブロックされた場合は、ブロックの 403 ボディにある correlation_id。または、trace_id と span_id（同じ AFT フラグのケースで、スパンにはどちらのモードでもフラグが含まれるため、引き続き利用できます）
list_evals	ビルド時に evals/ からバンドルされたマニフェストを読み込み、すべての pain-point および fault-tolerance eval の ID と件数を一覧表示します。パラメーター：なし
get_eval_result	特定の eval のアサーションを読み込みます。ソースの読み込みにはリポジトリのチェックアウトが必要です。存在しない場合はその旨を通知します。パラメーター：eval_id
replay_trace	オフラインでステップ実行するため、記録済みのトレースをそのまま（順序付きスパンと LLM／ツール属性を含めて）返します。**読み取り専用です。モデルやツールは再実行されません。**パラメーター：trace_id、include_tool_calls?

Claude での使用例

接続したら、Claude に次のように依頼できます。

「ガードレールによってブロックされた直近 5 件のトレースを表示して、何が発動したのか説明してください。」

「直近 1 時間の claude-haiku-4-5 と claude-sonnet-4-6 を使用したトレースのレイテンシを比較してください。」

「eval が実行するアサーションを表示してください。」

認証

TRACELANE_API_KEY 環境変数は MCP env ブロック経由で渡します。サーバーは 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> を含める必要があります。テナントはゲートウェイ経由でリクエストごとに特定されます。ホスト型エンドポイントは提供されません。

セキュリティ上の不変条件

• 読み取り専用です。 書き込みツールは登録されません。ツールは上記の 8 つのみで、すべて読み取り専用です。
• テナント分離。 ゲートウェイモードでは、すべての読み取りがテナントスコープのゲートウェイルート（crates/gateway/src/trace_reads.rs）を通じて行われます。テナントはサーバー側でベアラーのクレームから取得され、このサーバーがテナント ID を送信したり、参照したりすることはありません。セルフホストモードでは、すべての ClickHouse クエリに WHERE tenant_id = {tenantId: String} が含まれます（パラメーターとしてバインドされ、文字列補間は行われません）。
• どちらのモードでも、tenant_id がツールのパラメーターになることはありません。 Stdio では、起動時に TRACELANE_API_KEY からゲートウェイ経由で一度だけ取得し、キーが拒否された場合は起動しません。HTTP では、ベアラートークンからリクエストごとに取得し、AsyncLocalStorage を通じてバインドします。
• 2xx 以外のゲートウェイレスポンスはツールエラーとして扱われ、空の結果にはなりません。 キーが取り消されている、キーが誤ったテナントのもの、キーに read スコープがない、または別のテナントのトレース ID が指定された場合、読み取り結果は [] ではなく、ゲートウェイ独自のステータスとメッセージを含む isError: true になります。
• eval ID がファイルシステムに渡されることはありません。 get_eval_result はバンドルされたマニフェストで ID を照合し、マニフェストのパスを使用するため、パストラバーサル文字列でファイルを指定することはできません。
• TRACELANE_GATEWAY_URL は、ベアラーを送信する前に両方のモードで SSRF チェックされます。 開発環境以外では HTTPS のみ許可され、tracelane.dev のホストのみが対象となります。また、プライベート／CGNAT／IMDS の範囲は拒否されます。

運用者向けの注意： スパンの内容は保存時のまま返されます。このサーバーに設定する API キーのスコープは、接続先のモデルに渡しても問題のないスパンを含むワークスペースに限定してください。

セルフホスト

# 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 strict、noUncheckedIndexedAccess: true
• リントとフォーマットには Biome を使用

ライセンス

Apache 2.0 — LICENSE を参照してください。