tracehub-mcp

tracehub-mcp

公式 MCP レジストリには io.github.mcpsmiths/tracehub-mcp として掲載されています（レジストリ独自の ?search= エンドポイントでは、最初に古いバージョンが表示されることがありますが、この完全一致名のエンドポイントには常に最新の isLatest リリースが反映されます）。また、mcprushにも掲載されています。

AI アシスタントからオブザーバビリティバックエンドに直接アクセスできるようにします。 tracehub-mcp は、Claude、Cursor、Windsurf、Gemini CLI、または任意の MCP クライアントから、LLM／GenAI アプリケーションの OpenTelemetry トレースをクエリし、その内容を分析できる MCP（Model Context Protocol）サーバーです。高コストの呼び出しの特定、エラーのデバッグ、モデルのパフォーマンス比較、トークン使用量の追跡などを行えるため、トレースの JSON をチャットウィンドウにコピーして貼り付ける必要はありません。

OpenTelemetry の gen_ai.* セマンティック規約にネイティブ対応しているため、プロンプト、生成結果、トークン使用量、終了理由を、単なる汎用的なスパン属性ではなく、第一級の概念として理解します。

tracehub-mcp は、traceloop/opentelemetry-mcp-server（Apache 2.0）のフォークとして始まりました。著作権表示とフォークの履歴については、NOTICEをご覧ください。現在は 8 つのバックエンドに対応し、セキュリティを強化したサーバーへと成長し、mcpsmithsのもとで独立して保守されています。このプロジェクトで新たに加わった内容については、以下の上流版との違いをご覧ください。

目次

• クイックスタート
• 対応バックエンド
• 上流版との違い
• インストール
• 設定
• 診断
• セキュリティに関する考慮事項
• プライバシーポリシー
• MCP クライアントのセットアップ
• ツールリファレンス
• 汎用フィルターシステム
• クエリの例
• 一般的なワークフロー
• 開発
• トラブルシューティング
• ロードマップ
• ライセンス
• サポート

クイックスタート

tracehub-mcp は PyPI で公開されています。インストール手順は不要です。uvx が取得して、そのまま実行します。

// claude_desktop_config.json
{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

または、Claude Code から直接実行することもできます。

claude mcp add tracehub-mcp -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://localhost:16686 -- uvx tracehub-mcp

これだけです。 アシスタントに 「過去 1 時間のエラーを含むトレースを表示して」 と尋ねてみてください。

Cursor、Windsurf、VS Code、Gemini CLI についてはMCP クライアントのセットアップをご覧ください。また、pip／pipx／ソースからのインストール方法についてはインストールをご覧ください。

サポート対象のバックエンド

• Jaeger — ローカル／セルフホスト可能で、最も一般的なオープンソースのトレースバックエンドです。認証は不要です（BACKEND_API_KEY を介して Bearer トークンを送信できますが、BACKEND_URL に埋め込まれた認証情報は拒否されます）。
• Grafana Tempo — ローカルまたは Grafana Cloud で利用でき、TraceQL ネイティブの検索に対応しています。
• Traceloop — クラウド LLM オブザーバビリティプラットフォームで、API キー認証が必要です。
• Datadog — クラウド APM で、API キーと Application キーの両方が必要です。
• Sentry — クラウドまたはセルフホスト可能で、認証トークンと組織のスラッグが必要です。
• AWS X-Ray — boto3 を介した SigV4 署名に対応しており、AWS リージョンと標準の AWS 認証情報が必要です（API キーではありません）。OTel スパン属性は、既定ではインデックス化されない X-Ray セグメントの メタデータ に格納されるため（クエリ可能なのは アノテーション のみ）、ネイティブのサーバーサイドフィルタリングは他のバックエンドより限定的です。詳しくはバックエンド対応マトリックスをご覧ください。
• New Relic — NerdGraph GraphQL API を使用し、User API キー（Ingest／License キーではありません）とアカウント ID が必要です。実アカウントで検証せずに実装されています。未検証の前提条件の詳細については、以下のバックエンド固有の設定セクションと、backends/newrelic.py のモジュール docstring をご覧ください。
• Honeycomb — Query Data API を使用し、Configuration Key とデータセットのスラッグが必要です。実アカウントで検証せずに実装されています。また、調査の結果、クエリを実行して結果を取得する唯一の方法であるプログラム用 Query Data API は、Enterprise プラン限定としてドキュメント化されていることがわかりました。詳しくは、以下のバックエンド固有の設定セクションと、backends/honeycomb.py のモジュール docstring をご覧ください。

8 つすべてが同じ BaseBackend インターフェースを実装しているため、どのバックエンドをサーバーに指定しても、すべての MCP ツールを同じように利用できます。バックエンドごとの設定については、設定をご覧ください。

Upstream 版との違い

Upstream の opentelemetry-mcp-server には、Jaeger、Tempo、Traceloop が含まれていました。tracehub-mcp は、Datadog と Sentry を完全なバックエンドとして追加しています。薄いラッパーではなく、すべてのツール（検索、スパン検索、トレースの補完、サービス検出、ヘルスチェック）を完全に実装しています。その過程で、Upstream から引き継いだ 3 つを含む 5 つすべてのバックエンドを強化し、一貫した基準を満たすようにしました。

• クラウドバックエンドで HTTPS のみを強制 します。Datadog と Sentry は、平文で送信すべきではないベアラートークン、または API キーと App キーのペアで認証するため、通常の http:// URL に対しては起動を拒否します。
• クエリインジェクションを防ぐエスケープ処理 を行います。Datadog のスパン検索クエリや Sentry の Discover クエリに埋め込まれる値は、すべてエスケープして完全一致で引用符付けします。MCP ツールの filters パラメーターから渡されるため、信頼できない可能性が見えにくいフィールド名も、クエリ文字列に埋め込む前に許可リストのパターンに照らして検証し、細工されたフィールド名による構造的なインジェクションを防ぎます。
• カーソルでページネーションするすべてのバックエンド（Datadog、Sentry）で、ページネーションに上限を設けています。検索は、指定された limit に達するか、バックエンドが次のカーソルを返さなくなった時点のいずれか早い方で停止するため、1 回のツール呼び出しが際限のないクロールに発展することはありません。
• ID の完全一致を再検証 します。バックエンドの検索 API が完全一致ではなく近傍の結果を返す可能性がある場合（特に、Datadog でグループ化されたスパンからトレースを再構築する場合）、結果を返す前に、要求された ID と完全に一致するかを再確認します。
• 構築したバックエンドでは、レスポンスが不正な場合に データを捏造しません。Datadog と Sentry は、欠落したタイムスタンプを now() に置き換えたり、欠落した service_name／operation_name を文字列リテラルの "unknown" で補ったりせず、スパン自体を拒否します。捏造された値は、トレースの順序、期間の集計、サービスまたは操作ごとにグループ化するあらゆるツールを、気づかないうちに破損させるためです。（Upstream から引き継いだ 3 つのバックエンド、Jaeger、Tempo、Traceloop はこの方針より前に作られたもので、後からこの対応は加えていません。これは見落としではなく、意図的に対象範囲を限定した結果です。共有コードや継承したコードに手を加える際は、完全な回帰テストでカバーされていなければ変更しないという、このプロジェクト自身の前例に倣っています。）

これらはすべて、458 件のテストが成功（2 件スキップ、回帰なし）、ruff check と mypy --strict の実行がクリーンに完了したこと、さらに新しいバックエンドに対して CodeRabbit による敵対的レビューを 2 回実施したことによって裏付けられています。

インストール

tracehub-mcp は PyPI で公開されています。普段のワークフローに合った方法を選んでください。どれを選んでも同じです。

オプション 1：uvx（インストール不要）

uvx tracehub-mcp --backend jaeger --url http://localhost:16686

上記の クイックスタート の設定では、この方法を使っています。uv がパッケージを取得し、tracehub-mcp のエントリーポイントを一度に実行するため、実行のたびにディスク上に何も残りません。

オプション 2：pip／pipx

pipx install tracehub-mcp
# or: pip install tracehub-mcp

tracehub-mcp --backend jaeger --url http://localhost:16686

オプション 3：クローンしてソースから実行

git clone https://github.com/mcpsmiths/tracehub-mcp.git
cd tracehub-mcp
uv sync

uv run tracehub-mcp --backend jaeger --url http://localhost:16686

ローカルで開発する場合、特定のコミットに固定したい場合、または開発ツールをインストールしたい場合（uv sync --group dev）に使ってください。

オプション 4：Docker

# The image's CMD binds 0.0.0.0 inside the container, so a caller token is
# mandatory: clients send it as `Authorization: Bearer $MCP_HTTP_BEARER_TOKEN`.
export MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32)
docker run --rm -p 8000:8000 \
  -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://host.docker.internal:16686 \
  -e MCP_HTTP_BEARER_TOKEN \
  -e MCP_ALLOWED_HOSTS=localhost \
  ghcr.io/mcpsmiths/tracehub-mcp:latest

バックエンドの応答はバッファリングされる前に BACKEND_MAX_RESPONSE_BYTES（デフォルトではデコード後 64 MiB）で上限が設定されますが、多数のセッションを処理するコンテナには Docker 自体の安全策も有効です。--memory 1g --restart unless-stopped（または Compose の同等の設定）を追加すると、メモリを使い果たしたプロセスを封じ込め、オペレーターの介入なしに再起動できます。

デフォルトでは HTTP トランスポート（イメージの CMD）で実行され、MCP_HTTP_BEARER_TOKEN が設定されていないと起動を拒否します。明示的に -e MCP_ALLOW_UNAUTHENTICATED_HTTP=true を指定すれば認証を無効にできますが、公開ポートに接続できるすべての接続元に、バックエンドの全読み取り範囲が与えられます。クライアントは Authorization: Bearer <token> を指定して http://localhost:8000/mcp に接続します。/health と /ready（イメージの HEALTHCHECK）にはトークンは不要です。CMD は 0.0.0.0 にバインドするため、MCP_ALLOWED_HOSTS が設定されている場合にのみ、コンテナは Host ヘッダーを検証します。クライアントが使用するホスト名（上記の例では localhost、実際のデプロイでは公開名）を必ず設定してください。* を指定すると Host の検証が無効になり、ホスト名との併用はできません（サーバーは起動を拒否します）。これは、ローカルバイナリではなく docker を指す command／args のペアを設定する MCP クライアント（Cursor、Windsurf）でも使用する形式です。args に同じ -e MCP_HTTP_BEARER_TOKEN=... を渡してください。

前提条件： Python 3.11 以降、およびオプション 1 と 3 では uv、オプション 4 では Docker が必要です。

設定

設定は環境変数、CLI フラグ、またはその両方で指定できます。優先順位：CLI 引数 > 環境変数 > デフォルト値。

# .env (see .env.example)
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

# Equivalent via CLI flags
tracehub-mcp --backend jaeger --url http://localhost:16686

すべての設定オプション

既知のサードパーティへの送信依存関係： 基盤となるFastMCPフレームワークは、起動バナーを表示する際、12時間ごとにPyPI（https://pypi.org/pypi/fastmcp/json）を確認して、新しいFastMCPリリースがないか調べます。これはFastMCP自体の動作であり、tracehub-mcpの動作ではありません。また、上記のOTel自己計装とは無関係です。ネットワークに接続できない場合、この確認はエラーを出さずに失敗します。ネットワークが制限された環境やエアギャップ環境では、FASTMCP_CHECK_FOR_UPDATES=offで無効にするか、FASTMCP_SHOW_SERVER_BANNER=falseでバナー全体を非表示にしてください。

バックエンド固有のセットアップ

BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

BACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200

BACKEND_TYPE=tempo
BACKEND_URL=https://tempo-prod-XX-prod-XX-XXXX.grafana.net
BACKEND_TEMPO_INSTANCE_ID=your_stack_instance_id
BACKEND_API_KEY=your_cloud_access_policy_token

BACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here

BACKEND_TYPE=datadog
# US site (default): https://api.datadoghq.com
# EU site:            https://api.datadoghq.eu
BACKEND_URL=https://api.datadoghq.com
BACKEND_API_KEY=your_api_key_here
BACKEND_APP_KEY=your_application_key_here

BACKEND_TYPE=sentry
# SaaS (may be region-specific, e.g. https://us.sentry.io):
BACKEND_URL=https://sentry.io
BACKEND_API_KEY=your_auth_token_here
BACKEND_SENTRY_ORG=your-org-slug
# Optional: narrow queries to one project
BACKEND_SENTRY_PROJECT=your-project-slug

BACKEND_TYPE=xray
# Decorative only - never dereferenced for a live request. Keep it
# consistent with BACKEND_AWS_REGION by convention.
BACKEND_URL=https://xray.us-east-1.amazonaws.com
BACKEND_AWS_REGION=us-east-1

BACKEND_TYPE=newrelic
# US datacenter (default): https://api.newrelic.com/graphql
# EU datacenter:            https://api.eu.newrelic.com/graphql
BACKEND_URL=https://api.newrelic.com/graphql
BACKEND_API_KEY=your_user_api_key_here
BACKEND_NEWRELIC_ACCOUNT_ID=1234567

BACKEND_TYPE=honeycomb
# US instance (default): https://api.honeycomb.io
# EU instance:            https://api.eu1.honeycomb.io
BACKEND_URL=https://api.honeycomb.io
BACKEND_API_KEY=your_configuration_key_here
BACKEND_HONEYCOMB_DATASET=your-dataset-slug

Go／no-go の判断に関わるリスクであり、単なる未確認事項ではありません。 このバックエンドの調査では、クエリを実際に実行してデータを取得する唯一の方法であるプログラム用 Query Data API（create-query-result と get-query-result）は、Enterprise プラン限定とドキュメントに記載されていることがわかりました。Free および Pro アカウントでは、API 経由でクエリ仕様を作成できますが、実行はできません。このバックエンドは 402／403 が返された場合に明確な HoneycombEnterpriseRequiredError を発生させますが、Enterprise 以外のアカウントで返される正確なステータスコードは実環境で確認されておらず、このバックエンドは実アカウント（Enterprise を含む）を一切使わずに構築されました。本番環境でこのバックエンドを利用する前に、未確認の前提事項をすべて確認してください。これには、Honeycomb の集計指向の Query API からスパン単位の生データ行を抽出する方法も含まれます。詳細は backends/honeycomb.py のモジュール docstring を参照してください。

トランスポートモード

# stdio (default) — local use, Claude Desktop, single process
uvx tracehub-mcp
tracehub-mcp                      # pipx/pip install
uv run tracehub-mcp               # from-source install

# HTTP — remote access, multiple clients, network deployment, sample applications
# Loopback (the default --host) needs no token: same-machine clients use http://127.0.0.1:8000/mcp
uvx tracehub-mcp --transport http --port 8000
# Every interface: a caller token is mandatory (or the explicit --allow-unauthenticated-http opt-out)
export MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32)
uvx tracehub-mcp --transport http --host 0.0.0.0 --port 8000
tracehub-mcp --transport http --host 0.0.0.0 --port 8000              # pipx/pip install
uv run tracehub-mcp --transport http --host 0.0.0.0 --port 8000       # from-source install

HTTP トランスポートでは、クライアントは http://<host>:<port>/mcp（MCP クライアント間の互換性を保つための streamable-HTTP）に接続します。また、MCP_HTTP_BEARER_TOKEN が設定されている場合は、すべてのリクエストで Authorization: Bearer <token> を送信します。トークンがない、または正しくない場合は、WWW-Authenticate: Bearer チャレンジを伴う 401 が返され、セッションは開始されません。uvicorn のリクエストごとのアクセスログは、デフォルトで無効です（--access-log／MCP_ACCESS_LOG=true で再度有効にできます。有効にすると、クエリ文字列、フラグメント、マトリックスパラメーター（;。uvicorn では %3B としてログに記録されます）、およびパーセントエンコードされた ?／# が各行から除去され、ログに記録されるパスは 2 KiB で切り詰められます。ただし、パストークンは引き続きログに記録されます）。アクセスログが有効だと、誤設定されたクライアントがクエリ文字列にトークンを含めた場合、そのトークンを含む完全なリクエストターゲットがサーバーログに書き込まれてしまいます。また、アクセスログに必要な情報はありません。リクエスト単位の診断情報は、サーバー独自の、サイズに上限を設けた Host／Origin 拒否ログとレート制限ログ、低速リクエストの WARNING、および有効にした場合の OTel スパンから取得できます。

ループバックにバインドすると、Host ヘッダーも自動的に検証されます（ループバック名とバインド先のアドレスは許可され、それ以外には 421 が返されます）。これにより、ブラウザーページからの Origin を含まない GET に、攻撃者の名前が Host に指定されて届く DNS リバインディングの脆弱性を防ぎます。同じホスト上のリバースプロキシが 127.0.0.1 に転送し、公開用の Host を維持する場合（nginx のデフォルトの proxy_set_header Host $proxy_host では維持されません）は、その名前を --allowed-hosts／MCP_ALLOWED_HOSTS に指定してください。ネットワークインターフェースにバインドする場合も、公開ホスト名を --allowed-hosts に指定すれば同じ保護が適用されます。--allowed-hosts '*' を指定すると保護は無効になり、単独で指定する必要があります（* と名前を混在させたリストは起動時に拒否されます）。

Fly.io： ワンクリックの fly mcp launch コマンドは、stdio トランスポートのサーバーのみをサポートしています。したがって、このサーバーの --transport http モードはデプロイできません。Fly.io で tracehub-mcp を HTTP トランスポートで実行するには、代わりに fly.toml と fly deploy を使う手動の手順が必要です。

診断

実際の MCP クライアントに接続する前に、設定を検証します。

tracehub-mcp doctor --backend jaeger --url http://localhost:16686

[OK] Configuration loaded and validated
[OK] Backend constructed: jaeger @ http://localhost:16686/
[OK] Health check: healthy
[OK] Connectivity probe (list_services): 2 service(s)

doctor はメインコマンドと同じ --backend／--url などのフラグを受け付け、いずれかのステップが失敗するとゼロ以外の終了コードを返します。これに対し、通常のサーバー起動ではバックエンドを遅延初期化し、初回のヘルスチェックに失敗しても意図的に実行を継続します。

サーバーを起動せずに、解決済みの設定全体（環境変数と CLI の上書きをマージしたもの）を確認するには、次のようにします。

tracehub-mcp --print-config --backend jaeger --url http://localhost:16686

シークレット（--api-key／--app-key）は、実際の値ではなく api_key_set／app_key_set のブール値として報告されます。

セキュリティに関する考慮事項

このサーバーが返すトレースおよびスパンのデータ（属性値、エラーメッセージ、オペレーション名）は、tracehub-mcp 自体ではなく、オブザーバビリティバックエンドが計測しているアプリケーションに由来します。そのため、信頼できるサーバー（このサーバー）が MCP クライアントに返すデータであっても、ウェブページやファイルと同じ種類の、根本的に信頼できない外部コンテンツです。

• HTTP トランスポートでは、すべてのツールがバックエンドの認証情報を使って実行されるため、呼び出し元を認証してください。 --transport http は、デフォルトでループバック（127.0.0.1）にバインドされます。ネットワークインターフェースでサービスを公開する場合（--host 0.0.0.0、Docker イメージの CMD）、MCP_HTTP_BEARER_TOKEN が必要です（クライアントは Authorization: Bearer <token> を送信します）。--allow-unauthenticated-http を渡して、ポートに到達できるすべてのピアがバックエンドの読み取り権限をすべて取得することを受け入れない限り、サーバーはトークンなしでの起動を拒否します。あるいは、ループバックへのバインドを維持し、プライベートネットワーク上で認証を行うリバースプロキシの背後に配置してください。/health と /ready ではトークンは必要ありません。
• バックエンドの認証情報を BACKEND_URL に含めないでください。 user:password@host 形式の URL は、サポートされている代替手段（BACKEND_API_KEY、または Basic 認証の場合は BACKEND_TEMPO_INSTANCE_ID と BACKEND_API_KEY）を示すメッセージとともに、起動時に拒否されます。これは、URL がログに記録され、--print-config／doctor によって出力され、/ready のレスポンス本文やツールエラーに含まれてクライアントに届くバックエンドエラーのテキストにもそのまま埋め込まれるためです。多層防御として、プロセスから外部に出るすべての URL とバックエラー文字列からユーザー情報部分を削除し、さらにルートログハンドラーが、トレースバックを含むすべてのログレコードからこれを秘匿します。
• バックエンドのレスポンスによって、サーバーが別のホストに誘導されることはありません。 共有 HTTP クライアントが送信するすべてのリクエスト（バックエンド自身の 3xx Location が要求するリダイレクトの各段階を含みます）は、そのオリジン（スキーム、ホスト、ポート）が設定済みの BACKEND_URL のオリジンと一致しない場合、拒否されます（バックエンドと同じホスト上の別のポートやスキームへのリダイレクトも拒否されるため、最終的なスキームとポートを使って BACKEND_URL を設定してください）。また、クラウドインスタンスのメタデータアドレス（169.254.169.254、10 進数／16 進数／8 進数表記の IPv4 アドレス、168.63.129.16、metadata.google.internal）に解決される場合も拒否されます。API 呼び出しを別のホスト名へリダイレクトするバックエンドやリバースプロキシはサポートされていません。代わりに、最終的なホストを BACKEND_URL に設定してください。1 つのリクエストのすべての段階を通じて、クライアントの再試行は最大 2 回、Retry-After の合計待機時間は最大 10 秒、リダイレクトは最大 5 回です。また、どの段階でも max(30 s, 4 x BACKEND_TIMEOUT) に達すると処理を打ち切るため、バックエンドがツール呼び出しの速度を制御することはできません。
• バックエンドのデータは信頼できない入力として扱ってください。 tracehub-mcp からトレース／スパンデータを受け取る LLM クライアントは、他の外部ツールの出力と同様に注意して扱う必要があります。スパン属性やエラーメッセージは、従うべき指示ではなく、推論の対象となるアプリケーションデータです。どのような表現で書かれていても同じです。
• これは既知の MCP リスクカテゴリであり、tracehub-mcp 固有のリスクではありません。 OWASP の GenAI Security Project は、Practical Guide for Secure MCP Server Development でこの問題を取り上げています。また、Anthropic のエンジニアリングガイダンスである How We Contain Claude では、ツール自体が信頼できる場合でも、ツールの出力は攻撃対象となることが明確に述べられています。
• 実際の影響： 信頼できないユーザー入力を処理するアプリケーション（例：顧客向けチャットボット）のトレースをクエリする場合、ユーザーがそのアプリケーションに入力した悪意あるコンテンツが、このサーバーが返すスパン属性に含まれる可能性があることに注意してください。その結果、コンテンツが LLM クライアントのコンテキストに入り込む可能性があります。

プライバシーポリシー

tracehub-mcp はセルフホスト型ソフトウェアであり、メンテナーが運営するサービスやアカウントはありません。そのため、独自にデータを収集することはありません。ポリシーの全文は PRIVACY.md をご覧ください。ソフトウェアが扱うデータ、ネットワーク通信の送信先、シークレットと自己計装の取り扱いについて説明しています。

MCP クライアントの設定

以下のすべての例では、インストール手順が不要な uvx tracehub-mcp を使用します。別の方法でインストールした場合は、tracehub-mcp（pip/pipx install）または uv run tracehub-mcp（ソースから実行する場合は --directory /absolute/path/to/tracehub-mcp）に置き換えてください。詳しくはインストールをご覧ください。

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "datadog",
        "BACKEND_URL": "https://api.datadoghq.com",
        "BACKEND_API_KEY": "your_api_key_here",
        "BACKEND_APP_KEY": "your_application_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "sentry",
        "BACKEND_URL": "https://sentry.io",
        "BACKEND_API_KEY": "your_auth_token_here",
        "BACKEND_SENTRY_ORG": "your-org-slug"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "/absolute/path/to/tracehub-mcp/start_locally.sh"
    }
  }
}

claude mcp add tracehub-mcp -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://localhost:16686 -- uvx tracehub-mcp

claude mcp list
claude "Show me traces with errors from the last hour"

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "servers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

gemini "Analyze token usage for gpt-4 requests today"

ツールリファレンス

tracehub-mcp は 19 個の MCP ツールを公開します。

バックエンドのサポート一覧

_{* Jaeger でスパンを検索するには、service_name パラメーターが必要です。
† Datadog、AWS X-Ray、New Relic、Honeycomb には、トレースレベルの 検索 API がありません（X-Ray の BatchGetTraces は完全一致する ID で取得します）。検索（スパン、X-Ray のトレースサマリー、NRQL Span イベント、または Honeycomb のブレークダウングループ）とデータの補完によってトレースを再構築し、すべての結果を要求された ID と完全一致するか再確認します。
‡ Sentry と New Relic にはネイティブのトレース検索エンドポイントがあります（Datadog と Honeycomb にはありません）。そのため、get_trace はエンドポイントを直接呼び出します。一方、search_traces は、どちらのバックエンドも検索機能がスパン中心であるため、まずスパン／NRQL 検索を使って候補のトレース ID を見つけます。
§ AWS X-Ray がネイティブでフィルターできるのは、サービス名、継続時間、エラー／障害／スロットリングから算出されるステータスのみです。OTel 属性（すべての gen_ai.* フィールドを含む）は、デフォルトではインデックス付きの アノテーション ではなく、インデックス化されないセグメント メタデータ に格納されるため、FilterExpression に渡さず、常にクライアント側で適用します。
¶ New Relic：search_spans は、NRQL の十分に文書化されたフラットな行形式から gen_ai.* 属性を直接読み取ります。一方、search_traces／get_trace は、NerdGraph の distributedTracing.trace レスポンス内にある attributes フィールドの形式について、未検証の前提にも依存しています。この問題は、補完した結果に元の検索行の属性を重ね合わせることで軽減しています。Honeycomb：gen_ai.* 属性は、他のすべてのフィールドに使われるのと同じブレークダウン列の手法（モジュールの docstring のポイント 2）で抽出します。これも同様に未検証の抽出方法です。
♦ 上記の Honeycomb の「検索」／「ID によるトレースの取得」行にあるチェックマークは、すべて Query Data API に依存しています。このバックエンドの調査によると、この API は Enterprise プラン限定として文書化されています。Free／Pro アカウントでは、これらの機能をまったく利用できない場合があります。上記の Honeycomb セットアップのセクションを参照してください。}

主要なツールの詳細

search_traces

{
    "service_name": "my-app",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T23:59:59Z",
    "gen_ai_system": "openai",
    "gen_ai_request_model": "gpt-4",
    "min_duration_ms": 1000,
    "has_error": false,
    "limit": 50,
}

パラメーター：service_name、operation_name、start_time／end_time（ISO 8601）、min_duration_ms／max_duration_ms、gen_ai_system、gen_ai_request_model、gen_ai_response_model、has_error、tags、filters（汎用フィルターシステムを参照）、limit（1～1000、デフォルトは 100）。トークン数を含むトレースのサマリーを返します。

get_trace

{"trace_id": "abc123def456"}

トレースツリー全体を返します。属性を含むすべてのスパン、LLM スパンの解析済み OpenTelemetry gen_ai.* データ、スパンごとのトークン使用量、エラー情報、各スパンの生の events（例：gen_ai.evaluation.result、またはインストルメンテーションによって出力されたその他のイベント。固定された名前のセットに限定されません）が含まれます。

triage_trace

{"trace_id": "abc123def456", "detail_level": "summary"}

エージェントが診断を毎回導き直せるように生のトレースデータを返すのではなく、診断を直接生成します。具体的には、クリティカルパス（トレース全体のレイテンシーの原因となった「最後に終了した子」の連鎖）、自己時間（子の分を差し引いたレイテンシーへの寄与）で順位付けした上位スパン、そしてトレースにエラーが含まれる場合は、エラーチェーン内で最も深いエラースパンを根本原因の候補として提示します（confidence: "high"。同じ深さのエラーチェーンが複数あり、原因の特定が曖昧な場合は "medium"）。エラーがない場合は、自己時間が最も長いスパンを純粋なレイテンシーの診断として提示します（confidence: "low"）。LLM 呼び出しを行わない決定論的な処理で、get_trace がすでに取得したスパンデータを使用するため、設定済みのあらゆるバックエンドで動作します。detail_level: "full" を指定すると、判定がエラーに基づく場合に、診断された根本原因の生のエラー詳細（メッセージ／型／スタックトレース）も追加します。トレースの深さにかかわらず、結果のサイズには上限があります。summary モードでは、error_chain と critical_path はそれぞれ最大 25 個のスパンを列挙します。最初の 5 個と最後の 20 個の間に、[K intermediate span(s) elided] という項目を 1 つ明示的に挿入し、理由の説明に実際の深さを記載します。detail_level: "full" では上限が 1000 個に引き上げられます。ルートスパンがないトレース（親の循環）は、深さとしてではなく、その旨を confidence: "low" で報告します。

correlate_trace

{"trace_id": "abc123def456"}

2 つ目の、独立して設定されたバックエンドで対応するトレースを探します（例：Datadog のトレースと、それに続く Sentry のエラーを関連付けます）。まずセカンダリバックエンドで trace_id の直接一致を試み（confidence: "high"）、一致しない場合は、時間枠とサービス名の重なりに基づくヒューリスティック検索に切り替えます（confidence: "low"）。プライマリトレース内のサービス名ごとに 1 回検索するため、search_traces に service_name を必要とする Jaeger などのバックエンドでも動作します。検索対象は、スパン数の多い上位 10 サービスまでに制限されるため、1 つのトレースからセカンダリバックエンドへのクエリが何百件にも増えることはありません。各一致結果には root_cause_consistent も含まれます。比較可能なエラーがどちらのトレースにもない場合は null、それ以外の場合は、両方のトレースでエラーと、そのエラーの起点となるサービスが一致するかどうかを true／false で示します（triage_trace と同じエラーチェーンのロジックを再利用します）。これはベストエフォートの相関であり、結合を保証するものではありません。結果には、固定の limitations（クロックスキュー、サンプリングの不一致、トレースの可視性が不完全であること、および通常の W3C Trace Context の伝播が行われていてもベンダー間でトレース ID の連続性が保証されないこと）に加えて、呼び出しごとの切り詰めに関する注記が常に含まれます。ヒューリスティック検索の時間枠は、プライマリトレースのスパンが示す範囲の広さにかかわらず、プライマリトレースの開始から 24 時間までに制限されるため、1 つのトレースによってセカンダリバックエンドの数年分のデータがスキャンされることはありません。また、10 サービスの上限を超えたサービスがスキップされた場合は、その旨が結果に示されます。SECONDARY_BACKEND_TYPE／SECONDARY_BACKEND_URL で設定されたセカンダリバックエンドが必要です（設定項目一覧を参照）。設定されていない場合は、明確なエラーが発生します。

get_llm_usage

{
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T23:59:59Z",
    "service_name": "my-app",
    "gen_ai_system": "openai",
    "limit": 1000,
}

プロンプト／生成／合計トークン数を、モデル別およびサービス別に集計し、リクエスト数とともに返します。

list_services — パラメーターなし。計装済みサービス名の一覧を返します。

find_errors

{"start_time": "2024-01-15T14:00:00Z", "service_name": "my-app", "limit": 50}

エラーメッセージ、エラーの型、切り詰められたスタックトレース、および LLM 固有のエラー情報を返します。

list_llm_models / get_llm_model_stats / get_llm_expensive_traces / get_llm_slow_traces / list_llm_tools_tool / search_spans_tool / list_sessions / get_session_stats / compare_time_windows / investigate_cost_spike / investigate_error_spike / get_prompt_version_stats の詳細と具体例は、CLAUDE.md に記載されています。この README では各ツールに共通する構造を説明し、LLM 分析ツールの正確なパラメーターとレスポンスフィールドについては、CLAUDE.md を詳しいリファレンスとして参照してください。

汎用フィルターシステム

search_traces と search_spans_tool は、より高度なクエリを実行するために、シンプルな名前付きパラメーターに加えて（またはその代わりに）filters リストを受け取ります。各フィルターは次のとおりです。

{
  "field": "gen_ai.usage.total_tokens",
  "operator": "gt",
  "value": 5000,
  "value_type": "number"
}

• field — ドット区切りの属性名。例：gen_ai.usage.prompt_tokens、traceloop.span.kind、service.name（1～256 文字）
• operator — 下の表を参照してください
• value — 単一の値（大半の演算子の場合）、または values — リスト（in、not_in、between の場合。値は最大 100 個）
• value_type — "string"、"number"、または "boolean"

制限と検証。 1 回の呼び出しで受け付けられるのは、最大 50 個の filters と 50 個の tags です（共通の上限ではなく、それぞれ独立した上限です）。各 in／not_in フィルターの values は最大 100 個で、field 名は 1～256 文字です。そのため、単一のクエリで生成できるバックエンドの句数には上限があります。値は送信前に、宣言された value_type に基づいて正規化されます。"number" の場合、"5000" のような数値文字列は受け付けられ、数値に変換されますが、"abc" のような数値以外の文字列、有限でない値、double で扱える範囲を超える整数は拒否されます。"boolean" では JSON の真偽値、または文字列 "true"／"false" を受け付けます。"string" では数値または真偽値を受け付け、文字列に変換します。不明なキーを含むフィルターオブジェクトは、黙って無視されるのではなく拒否されます。上限を超えた場合、または検証に失敗した場合、バックエンドへのリクエストが行われる前にツールエラーが返されます。

複数のフィルターは AND 条件で結合されます。従来のシンプルなパラメーター（service_name、gen_ai_request_model など）も引き続き使用でき、内部でフィルターに変換されます。自由に組み合わせてください。

サーバーでは、ハイブリッドフィルタリング戦略を使用します。対応するフィルターはバックエンドのネイティブなクエリ言語（Tempo の TraceQL、Datadog のスパン検索構文、Sentry の Discover 構文）に変換して適用し、ネイティブに表現できないものは、その後クライアント側で適用します。

例 — コストの高い OpenAI トレース：

{
  "filters": [
    { "field": "gen_ai.system", "operator": "equals", "value": "openai", "value_type": "string" },
    { "field": "gen_ai.usage.total_tokens", "operator": "gt", "value": 5000, "value_type": "number" }
  ]
}

セマンティック規約の属性一覧（gen_ai.* と従来の llm.*、プロバイダーごとのトークン命名の違い、終了理由の値、トークン計算のフォールバックチェーン）については、CLAUDE.md を参照してください。

クエリの例

コストの高い OpenAI オペレーションを検索する

質問： 「過去 1 時間の OpenAI トレースのうち、所要時間が 5 秒を超えるものを表示してください」

ツール呼び出し： search_traces

{
  "service_name": "my-app",
  "gen_ai_system": "openai",
  "min_duration_ms": 5000,
  "start_time": "2024-01-15T10:00:00Z",
  "limit": 20
}

応答：

{
  "traces": [
    {
      "trace_id": "abc123...",
      "service_name": "my-app",
      "operation_name": "chat.completions",
      "status": "OK",
      "duration_ms": 8250,
      "span_count": 3,
      "llm_span_count": 1,
      "total_tokens": 4523,
      "has_errors": false
    }
  ],
  "count": 1
}

モデルごとのトークン使用量を分析する

質問： 「今日、モデルごとに何トークン使用しましたか？」

ツール呼び出し： get_llm_usage

{
  "start_time": "2024-01-15T00:00:00Z",
  "end_time": "2024-01-15T23:59:59Z",
  "service_name": "my-app"
}

応答：

{
  "period": { "start_time": "2024-01-15T00:00:00Z", "end_time": "2024-01-15T23:59:59Z" },
  "filters": { "service_name": "my-app" },
  "summary": {
    "total_requests": 487,
    "total_prompt_tokens": 82140,
    "total_completion_tokens": 43290,
    "total_tokens": 125430
  },
  "by_model": {
    "gpt-4": { "requests": 156, "prompt_tokens": 58300, "completion_tokens": 26900, "total_tokens": 85200 },
    "gpt-3.5-turbo": { "requests": 331, "prompt_tokens": 23840, "completion_tokens": 16390, "total_tokens": 40230 }
  },
  "by_service": {
    "my-app": { "requests": 487, "prompt_tokens": 82140, "completion_tokens": 43290, "total_tokens": 125430 }
  }
}

エラーのあるトレースを見つける

質問： 「過去1時間のエラーをすべて表示してください」

ツール呼び出し： find_errors

{
  "start_time": "2024-01-15T14:00:00Z",
  "service_name": "my-app",
  "limit": 10
}

応答：

{
  "count": 1,
  "error_traces": [
    {
      "trace_id": "def456...",
      "service_name": "my-app",
      "operation_name": "chat.completions",
      "start_time": "2024-01-15T14:23:15Z",
      "duration_ms": 1200,
      "status": "ERROR",
      "span_count": 2,
      "llm_span_count": 1,
      "total_tokens": 310,
      "has_errors": true,
      "error_spans": [
        {
          "span_id": "span789...",
          "operation_name": "chat.completions",
          "service_name": "my-app",
          "status": "ERROR",
          "error_message": "RateLimitError: Too many requests",
          "error_type": "openai.error.RateLimitError",
          "is_llm_error": true,
          "llm_provider": "openai",
          "llm_model": "gpt-4"
        }
      ]
    }
  ]
}

モデルのパフォーマンスを比較する

質問： 「GPT-4 と Claude のパフォーマンスにはどのような違いがありますか？」

ツール呼び出し 1： gpt-4 の get_llm_model_stats

{ "model_name": "gpt-4", "start_time": "2024-01-15T00:00:00Z" }

ツール呼び出し 2： claude-3-opus の get_llm_model_stats

{ "model_name": "claude-3-opus-20240229", "start_time": "2024-01-15T00:00:00Z" }

トークン使用量が多い場合を調査する

質問： 「今日、最も多くのトークンを使用したリクエストはどれですか？」

ツール呼び出し： get_llm_expensive_traces

{ "limit": 10, "start_time": "2024-01-15T00:00:00Z", "min_tokens": 5000 }

よくあるワークフロー

コストの最適化

1. get_llm_expensive_traces — トークン数が最も多いリクエストを見つけます
2. get_llm_usage — 最もコストがかかっているモデルを確認します
3. 特定の trace_id に対して get_trace を実行 — プロンプトと応答の詳細を調べます

パフォーマンスのデバッグ

1. get_llm_slow_traces — レイテンシーの外れ値を特定します
2. find_errors — エラーのパターンを確認します
3. get_llm_model_stats — 切り詰めの原因となる終了理由の分布を確認します

モデルの導入状況を追跡する

1. list_llm_models — 実際に呼び出されているすべてのモデルを確認します
2. モデルごとに get_llm_model_stats を実行 — パフォーマンスを比較します
3. list_llm_models の結果を確認し、予期しないモデルやサービス（シャドー AI）がないか調べます

開発

git clone https://github.com/mcpsmiths/tracehub-mcp.git
cd tracehub-mcp
uv sync --group dev   # pulls in pytest, mypy, ruff, etc. for local iteration

# Tests (458 passed, 2 skipped at time of writing)
uv run pytest

# With coverage
uv run pytest --cov=opentelemetry_mcp --cov-report=html

# Format, lint, type-check
uv run ruff format .
uv run ruff check .
uv run mypy src/

CI（.github/workflows/ci.yml）では、プッシュのたびに Ruff と mypy（strict）を実行し、完全な pytest テストスイートも実行します。

mcpb pack mcpb/ で Claude Desktop バンドルをビルドします。mcpb/.mcpbignore は拒否リストです（mcpb は .gitignore を参照しません）。mcpb または mcpb の組み込みパターンで指定されていない mcpb/ 内のファイルはすべて、追跡対象かどうかにかかわらずアーカイブされます。クリーンなツリーからパックし（git status --short mcpb/ の出力が空であること）、バンドルを公開する前に表示されたファイル数を確認してください。

トラブルシューティング

バックエンドへの接続に関する問題：

curl http://localhost:16686/api/services   # Jaeger
curl http://localhost:3200/api/search/tags  # Tempo

認証エラー： キーが設定されていることを確認してください —

export BACKEND_API_KEY=your_key_here
# or: tracehub-mcp --api-key your_key_here

トレースが見つからない場合：

• 時間範囲を確認します（最近のタイムスタンプを使用してください）
• list_services でサービス名を確認します
• まずフィルターを指定せずに検索してみてください

トークン使用量がゼロと表示される場合：

• トレースに OpenTelemetry の gen_ai.*（またはレガシーの llm.*）インストルメンテーションが含まれていることを確認します
• get_trace でスパンの生属性を調べます

Datadog／Sentry 固有の問題： 設定にある各バックエンドのトラブルシューティングの説明を参照してください。

ロードマップ

以前ここで延期として掲載されていた2つのアイデアは、どちらもリリース済みです。

• エージェントネイティブのトリアージ — 生のトレースデータを返すだけでなく、根本原因の可能性が高いものを提示するツールです。上記のツールリファレンスにあるtriage_traceをご覧ください。
• バックエンドをまたいだ相関 — 個別に設定された2つ目のバックエンドにクエリを実行し、その結果と相関させます。上記のcorrelate_traceをご覧ください。これは、調査結果に基づき、スキーマレベルでの確実な結合ではなく、ベストエフォートのヒューリスティックな相関として提供されます（直接のtrace_id一致、または時間枠とサービスの重複を使ったフォールバック）。通常のW3C Trace Context伝播を行っていても、ベンダー間でトレースIDの連続性が保証されるわけではありません。

New RelicとHoneycombはその後、7番目と8番目のバックエンドとしてリリース済みです。どちらも実際のアカウントで検証することなく、調査とドキュメントのみをもとに構築されています。本番環境でいずれかに依存する前に未検証の点を正確に確認するには、それぞれのセットアップセクションをご覧ください。特にHoneycombには、実質的な導入可否のリスクがあります（プログラムから利用するQuery Data APIはEnterpriseプラン限定とドキュメントに記載されています）。現在、追加で調査中のバックエンドはありません。（Grafana Cloudはこのリストに含まれたことはありません。TempoのBasic Auth経由ですでに利用できます。上記のGrafana Tempoをご覧ください。）

上流プロジェクトの以前のロードマップから引き継いだ項目のうち、削除せずに上記の項目より優先度を下げたものは次のとおりです。モデルごとの統計と時間枠ごとの差分は、現在のget_llm_model_statsとcompare_time_windowsでそれぞれ扱えますが、特定の2つのモデルを直接比較する単一のツールはまだありません。1つのプロンプトについてバージョン間を比較するだけでなく、テンプレートをまたいでプロンプトパターンを幅広く分析する機能（後者はすでにget_prompt_version_statsで対応しています）、よく使われるクエリ用のMCPリソース、そしてSigNoz／ClickHouseバックエンドのサポートも対象です。組み込みの価格表を使ったコスト計算とクエリ結果のキャッシュレイヤーは、保留中ではなくリリース済みです。使用状況を報告するすべてのツール（例：ツールリファレンスのinvestigate_cost_spike）は、同梱されたlitellm価格表（src/opentelemetry_mcp/pricing/）に基づくcost_usd／cost_usd_is_partialのペアを返します。また、クエリ結果はQUERY_CACHE_TTL_SECONDS環境変数を使って、進行中のリクエストをまとめて処理しながらキャッシュされます。上記の設定一覧をご覧ください。

このREADMEの他の箇所に記載されている機能は、すべてリリース済みです。

コントリビューション

コントリビューションを歓迎します。PRを作成する前に、次の点を確認してください。

1. すべてのテストが成功すること：uv run pytest
2. コードがフォーマットされていること：uv run ruff format .
3. リントエラーがないこと：uv run ruff check .
4. 型チェックが成功すること：uv run mypy src/

ライセンス

Apache License 2.0 — 詳細はLICENSEをご覧ください。このプロジェクトはtraceloop/opentelemetry-mcp-serverのフォークです。完全な帰属表示とフォーク関係についてはNOTICEに記載されています。

サポート

• 課題と機能リクエスト： github.com/mcpsmiths/tracehub-mcp/issues
• 変更履歴： CHANGELOG.md
• コミュニティ： Traceloop Community Slack（上流プロジェクトのコミュニティチャンネルです。OpenTelemetry／GenAIトレースに関する一般的な質問を歓迎します）
• 関連リンク： Model Context Protocol · OpenTelemetry GenAI semantic conventions · traceloop/opentelemetry-mcp-server（上流プロジェクト）