Comet Opik

公式

Opikのログ、トレース、プロンプト、その他LLMからのテレメトリデータを自然言語でクエリし分析できます。

GitHub

217

Comet Opik MCPで何ができますか？

Opikワークスペースの参照と検索 — listを使用して、プロジェクト、実験、トレース、スパン、プロンプト、テストスイートを任意の名前フィルターとページネーション付きで一覧表示します。
ID、名前、URIによる任意のエンティティの検査 — readを使用してopik:// URIまたはUUIDを指定し、トレースやプロンプトのインライン化された子要素を含む完全な詳細情報を取得します。
トレース、スコア、コメント、プロンプトバージョンの記録 — writeを通じてトレースやスパンの作成・更新、フィードバックスコアの付与、プロンプトバージョンの保存、テストスイートの管理を行います。
LLM観測データに関する調査質問をOllieに依頼 — ask_ollieにクエリを送信し、実験の比較、回帰の診断、エンティティ横断的な洞察の統合（任意の途中スコアリング付き）を依頼します。
評価実験をエンドツーエンドで実行 — run_experimentをトリガーし、プロンプト、テストスイート、スコアラーを指定して評価実行を実施し、結果を記録します。
書き込み操作スキーマの内省 — schemaを使用して、ペイロード構築前に任意の書き込み操作に必要な正確なJSON構造と必須フィールドを取得します。

ドキュメント

Opik MCP サーバー

オープンソースの LLM 可観測性・評価プラットフォーム Opik の公式 Model Context Protocol (MCP) サーバーです。Comet が開発しました。 AI ホスト (Claude Code、Cursor、VS Code Copilot、MCP Inspector) を Opik ワークスペースに直接接続し、トレースの読み取り、スコアの記録、プロンプトバージョンの保存、 Opik 組み込み AI アシスタント Ollie への調査質問を、すべてチャットから行えます。

すでに Opik を運用しており、コーディングに使用している AI アシスタントから操作したい LLM エンジニア向けに構築されています。

古い npx opik-mcp から移行しますか？ TypeScript サーバーは非推奨であり、 2026-11-15 にサポート終了となります。MCP クライアント設定で npx -y opik-mcp を uvx opik-mcp@latest に置き換えてください。完全なガイド: legacy/typescript/MIGRATION.md。

You:    "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

インストール

opik-mcp は Python パッケージです (Python 3.13 以降が必要)。推奨される実行方法は uvx です。これは、最新の公開バージョンをオンデマンドで取得して実行するため、グローバルインストールや virtualenv の切り替えは不要です。

uv を一度インストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# or: brew install uv

Opik ワークスペースから以下の 2 つが必要です。

OPIK_API_KEY — comet.com/api/my/settings/ から取得します。
OPIK_WORKSPACE — ワークスペース名 (URL に表示される小文字の名前)。例: https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai。オプション — デフォルトは default (Opik SDK の規則) で、ローカル/OSS インストールでは正しい値です。名前付きワークスペースを使用するクラウドユーザーは設定する必要があります。COMET_WORKSPACE は非推奨のエイリアスとして受け付けられます。

プレリリースに関する注意: opik-mcp (Python) はまだ PyPI に公開されていません。最初の PyPI リリースが行われるまで、以下のスニペットの uvx opik-mcp を次のように置き換えてください。 uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE はオプションです。 以下のスニペットで OPIK_WORKSPACE 行/キーを省略すると、サーバーは default ワークスペースを使用します (ローカル/OSS インストールでは正しい値です)。名前付きクラウドワークスペースに接続する場合にのみ設定してください。

Claude Code

1 つのコマンドでサーバーを追加します。

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env OPIK_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp

または ~/.claude.json を直接編集します。

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Claude Code を再起動します。/mcp で確認します — opik-mcp が接続済みとして表示されるはずです。次に、チャットで "list my Opik projects" と尋ねます — Claude が list ツールを呼び出し、ワークスペースのプロジェクトが表示されます。

Cursor

~/.cursor/mcp.json (グローバル) または .cursor/mcp.json (プロジェクト) を編集するか、 Cmd+Shift+J → Features → Model Context Protocol を開きます。

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Cursor をリロードします。MCP パネルの opik-mcp の横にある緑色のドットが接続を確認します。チャットで "list my Opik projects" と尋ねます。

Cursor の 60 秒タイムアウト。 Cursor は、進行状況通知でリセットされないハードなツール呼び出しタイムアウトを適用します。長い ask_ollie ターンは Cursor で失敗します。既知のホスト制限を参照してください。

VS Code Copilot

ワークスペース (またはユーザー設定 JSON) の .vscode/mcp.json:

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "OPIK_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

ウィンドウをリロードします。Copilot Chat の MCP インジケーターに、サーバーが到達可能になると opik-mcp が表示されます。チャットで "list my Opik projects" と尋ねます。

MCP Inspector (手動テスト)

OPIK_API_KEY=<your-key> OPIK_WORKSPACE=<your-workspace> \
  npx @modelcontextprotocol/inspector uvx opik-mcp

セルフホスト Opik

ホスト設定の同じ env ブロックに COMET_URL_OVERRIDE (および Opik がデフォルト以外のパスにある場合は OPIK_URL) を追加します。

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

ask_ollie と run_experiment は Comet Cloud でのみ利用可能です — セルフホストではこれらの呼び出しはディスパッチ時に失敗するため、read / list / write を直接使用してください。OPIK_MCP_ANALYTICS_SOURCE="" を設定すると、テレメトリイベントの cloud-Comet ソースラベルがオプトアウトされます。

ツール

opik-mcp は、少数の成果指向のサーフェスを公開します — 完全なライフサイクル (読み取り → 注釈 → キュレーション → 作成 → 反復) をカバーする 6 つのツールです。

ツール	目的
`read`	ID / 名前 / `opik://` URI によるユニバーサル読み取り
`list`	オプションの名前フィルターとページネーション付きユニバーサルリスト
`ask_ollie`	Opik 組み込みアシスタントによる調査 / 統合
`write`	ユニバーサル書き込み — トレース/スパンのログ、スコア、コメント、プロンプトの保存、テストスイートと実験の管理
`schema`	書き込み操作スキーマのイントロスペクション (LLM が有効なペイロードを構築するために使用)
`run_experiment`	Ollie を介した評価実験のエンドツーエンド実行

`read`

あらゆる「X を見せて」という質問に対応する 1 つのツール。entity_type と id (UUID、または名前付け可能なタイプの場合は名前) または完全な opik:// URI を受け取ります。複合読み取り (trace、prompt) は子要素をインライン化するため、1 回の呼び出しで全体像が返されます。

サポートされているエンティティ: project、trace、span、test_suite、experiment、 prompt。名前ベースの検索は project、experiment、prompt、 test_suite で利用できます (低速 — 2 回の API 呼び出し — で、複数の一致を返す可能性があります)。

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")          # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

`list`

オプションの名前フィルターとページネーションを使用してコレクションを参照します。プロジェクトスコープのタイプ (trace、test_suite_item、prompt_version) には親 UUID が必要です。

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

調査質問、エンティティ間の統合、または Opik ドメインの専門知識が必要なあらゆる場合に使用します。 Ollie はワークスペースへの直接読み取りアクセス権を持ち、要求に応じてストリーム中に書き込み (スコア、コメント、テストスイートアイテム、プロンプトバージョン) を実行できます。

ask_ollie(query="Why are spans in project 'demo' slower this week than last?")
ask_ollie(query="Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.")

アシスタントの最終テキストと thread_id を返します。フォローアップ時にそれを渡してコンテキストを保持します — Ollie はスレッド間でメモリを持ちません。

YOLO モード (デフォルト)。 Ollie がストリーム中に実行する書き込みは、アクションごとの確認なしで実行されます。各自動承認は、opik_mcp.audit Python ロガーの JSON 監査行として記録されます。代わりに確認を要求するには、 OPIK_MCP_AUTO_APPROVE=disabled を設定します — Ollie の確認リクエストは、手動で再発行できる型付きエラーとして表示されます。

Comet Cloud でのみ利用可能です。

`write`

ユニバーサル書き込みディスパッチャー。operation + data を渡すと、ディスパッチャーはペイロードを検証し、適切な REST 動詞を適用して、バックエンドレスポンスを返します。

操作:

操作	説明
`trace.create`	単一のトレース (またはバッチ) をログに記録します。スパン/スコア/コメントの親。
`trace.update`	既存のトレースをファイナライズまたは修正します。
`span.create`	既存のトレースにスパン (またはバッチ) をログに記録します。
`score.create`	数値フィードバックスコアをトレース、スパン、またはスレッドに添付します。
`comment.create`	フリーテキストコメントをトレース、スパン、またはスレッドに添付します。
`prompt_version.save`	新しいプロンプトバージョンを保存します (存在しない場合は名前でプロンプトを作成します)。
`test_suite.create`	評価テストスイートを作成します。
`test_suite_item.upsert`	テストスイートにアイテムをアップサートします (常にエンベロープ形状)。
`experiment.create`	テストスイートをスコープとする実験を作成します。
`experiment_item.create`	トレース + dataset_item 行を実験に添付します。

write(operation="score.create", data={
  "target": "trace",
  "target_id": "7f2e3c8a-…",
  "name": "helpfulness",
  "value": 0.9,
  "reason": "great recovery"
})

`schema`

呼び出す前に、任意の書き込み操作の正確な JSON 形状と必須フィールドを検査します — data がどのように見えるべきかわからない場合に便利です。スキーマ、OAuth スコープ、および検証済みの例を 1 つ返します。純粋な検索であり、バックエンド呼び出しはありません。

schema(operation="score.create")
schema(operation="prompt_version.save")

`run_experiment`

Ollie を介して評価実験をエンドツーエンドで実行します。Opik の実験形状 (プロンプト、テストスイート、スコアラー) を反映する単一の experiment_config dict を受け取ります。Ollie が実行を実行し、結果を Opik 実験として書き戻します。

run_experiment(experiment_config={
  "test_suite_name": "qa-eval-v2",
  "prompt_name": "welcome-msg",
  # … see `schema(operation="experiment.create")` for the full shape
})

Comet Cloud でのみ利用可能です。

設定

すべての設定は環境変数です。必須のものは太字で示します。

ID / エンドポイント

変数	デフォルト	備考
`OPIK_API_KEY`	—	`ask_ollie` および認証済みの読み取り/書き込みに必要です。
`OPIK_WORKSPACE`	`default`	ワークスペース名。オプション — `default` (Opik SDK 規則) にフォールバックします。名前付きワークスペースを使用するクラウドユーザーは設定する必要があります。
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` の非推奨エイリアス (後方互換性)。両方が設定されている場合は `OPIK_WORKSPACE` が優先されます。
`COMET_WORKSPACE_ID`	—	オプションのワークスペース UUID。設定されている場合、BI が (変更可能な) ワークスペース名ではなく安定した ID で結合できるように、分析イベントにスタンプされます。
`COMET_URL_OVERRIDE`	`https://www.comet.com`	セルフホストの Comet ホスト、またはステージングの場合は `https://dev.comet.com` に設定します。
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api` から導出	Opik が Comet UI とは異なるホスト/パスにある場合にのみ上書きします。
`OPIK_DEFAULT_PROJECT_NAME`	未設定	設定されている場合、セッションごとの `instructions` blob は、ユーザーが別のプロジェクトを指定しない限り、すべてのツール呼び出しでこれを `project_name` として渡すように LLM に指示します。

サーバー / トランスポート

変数	デフォルト	備考
`OPIK_MCP_TRANSPORT`	`stdio`	ホスト起動の場合は `stdio`、ポートでリッスンする場合は `streamable-http`。
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn バインドホスト (`streamable-http` のみ)。
`OPIK_MCP_PORT`	`8080`	uvicorn バインドポート (`streamable-http` のみ)。
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload` を有効にするには `true` (開発のみ)。
`OPIK_MCP_AS_URL`	未設定	OAuth 認可サーバー URL。`/.well-known/oauth-protected-resource` (RFC 9728) でアドバタイズされ、AS-discovery プローブのプロキシターゲットとして使用されます。MCP ホストが HTTP 経由で OAuth ダンスをブートストラップするために必要です。
`OPIK_MCP_RESOURCE_URI`	未設定	このサーバーの正規の公開 URI。保護されたリソースメタデータで `resource` としてアドバタイズされ、`WWW-Authenticate` ヒントを導出するために使用されます。
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr ロガーしきい値。

トランスポートの選択

opik-mcp は、HTTP トランスポートで ローカル資格情報の検証を実行しません。適切な形式の Authorization: Bearer … (Opik API キーまたは opik_mcp_at_… OAuth アクセストークン) は、単一の認証実施ポイントである opik-backend にそのまま転送されます。デプロイメントの形状に応じてトランスポートを選択します。

シナリオ	トランスポート
MCP クライアントと Opik が同じマシン上にある (ローカル OSS インストール)	stdio (推奨 — 最もシンプルで、ポート不要、OAuth セットアップ不要)
ローカル MCP クライアント → リモート Opik (Comet cloud / セルフホスト)	`OPIK_API_KEY` を使用した stdio、または OAuth を使用した HTTP (`OPIK_MCP_AS_URL` がバックエンドを指す)
opik-backend と同じエッジの背後でホストされる opik-mcp	HTTP — ベアラーはリクエストごとにバックエンドによって検証されます

ローカル OSS インストールに関する注意: OSS バックエンドはリクエストを認証しないため、その前にある HTTP opik-mcp は OSS REST API 自体と同じくらいオープンです。共有ネットワークでは、デフォルトの 127.0.0.1 バインドを維持し (stdio を推奨)、注意してください。

Ollie / 長時間呼び出し

変数	デフォルト	備考
`OPIK_MCP_AUTO_APPROVE`	`enabled`	Ollie のストリーム中の書き込みを続行する前にアクションごとの承認を要求するには `disabled`。MCP `elicitation` 機能をアドバタイズするホストでは、ユーザーに yes/no プロンプトが表示されます。より単純なホストでは、リクエストは手動で再発行できる型付きエラーとして表示されます。
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie のストリーム中の確認プロンプトがキャンセルとして扱われるまでにユーザーを待機できる時間。`0` はバインドを無効にします (デバッグのみ)。
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie ポッドのコールドスタートポーリング上限。
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	コールドスタートポーリング間隔。
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	ウォッチドッグの周期 — ポッドがサイレント状態のときに `notifications/progress` ティックを発行し、ホストのタイムアウトを防ぎます。
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	`ask_ollie` が中止するまでのポッドサイレンスのハード上限。`0` は無効にします (デバッグのみ)。

テレメトリ

匿名利用イベント（イベントタイプとタイミングのみ — クエリ内容は含まれません）。APIキーのSHA-256ダイジェストが含まれるため、サポートがアカウントを特定できます。生のキーがプロセスの外部に出ることはありません。オプトアウト: OPIK_MCP_ANALYTICS_ENABLED=false

変数	デフォルト	備考
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	`false` に設定すると、すべてのテレメトリを無効化します。
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	ステージング用の上書き。
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	すべてのイベントに付与するタグ（`prod` / `staging` / `dev`）。
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	レシーバーが `on_prem=False` をマークするために使用します。オンプレミス環境では `""` または独自のドメインに上書きしてください。
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP接続タイムアウト。
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTPリクエスト全体のタイムアウト。

既知のホスト制限

MCP仕様では、ホストがツール呼び出しのタイムアウトを notifications/progress でリセットできます — opik-mcp はOllie SSEイベントごとに1回、さらに15秒間隔の監視ハートビートを発行します。現実の動作はまちまちです:

Claude Code — ツール呼び出しのタイムアウトに関するドキュメントはなく、ハートビートが message_end まで呼び出しを維持します。推奨。
Cursor — 60秒のハードタイムアウトがあり、進捗通知ではリセットされません （上流のバグ）。長時間のOllie実行は失敗します。ask_ollie クエリは焦点を絞ってください。
MCP Inspector — MAX_TOTAL_TIMEOUT が合計実行時間を制限します（デフォルト60秒）。長時間の操作ではInspector UIで値を上げてください。

呼び出しが停止した場合は、OPIK_MCP_LOG_LEVEL=DEBUG を設定してください — ハートビートの失敗（通常はホストの切断）は、opik_mcp.ask_ollie にデバッグレベルで記録されます。

トラブルシューティング

OPIK_API_KEY is required to use ask_ollie — 環境変数がサーバープロセスに渡っていません。Claude Code / Cursor / VS Codeでは、環境変数はシェルではなく、MCPサーバー設定の env ブロック内でのみ有効です。編集後はホストを再起動してください。

ask_ollie が2分後に "pod not ready" を返す — Ollie Podのコールドスタートが OPIK_MCP_POD_READY_TIMEOUT_S を超過しました。再試行してください — 通常、2回目の呼び出しはウォーム状態のPodにヒットします。

セルフホストOpikで ask_ollie / run_experiment がディスパッチエラーで失敗する — これらのツールはComet Cloudでのみ利用可能です。セルフホスト環境では read / list / write を直接使用してください。

Cursorの呼び出しが60秒でタイムアウトする — Cursorの既知のバグであり、opik-mcp の問題ではありません。Ollieクエリを短縮するか、ハードキャップのないClaude Codeで同じ操作を実行してください。

開発

git clone git@github.com:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

一般的なターゲット:

ターゲット	説明
`make install`	`uv sync --extra dev`
`make run`	MCPサーバーを実行します（デフォルトはstdio）。
`make run-dev`	DEBUGログ + uvicorn `--reload` で実行します。
`make dev`	`mcp dev`（Inspector開発モードラッパー）経由で実行します。
`make inspect`	実行中のサーバーに対してMCP Inspectorを起動します。
`make test`	`uv run pytest -q`。
`make test-live`	`dev.comet.com` に対するライブのエンドツーエンドテスト（`OPIK_API_KEY` + `OPIK_WORKSPACE` を設定）。
`make lint`	`ruff check` + フォーマットチェック。
`make format`	`ruff format` + `ruff check --fix`。
`make typecheck`	`mypy`。
`make check`	`lint + typecheck + test`。

リポジトリ構成:

opik-mcp/
├── src/opik_mcp/        ← server, tools, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

ヘルプ

バグや機能リクエストは Issueを作成
SDK / バックエンドのドキュメントは Opikドキュメント
質問は CometコミュニティSlack

v2からアップグレードしますか？ 従来のTypeScriptサーバーは引き続きnpmに opik-mcp@^2（npx -y opik-mcp）として公開されており、ソースは legacy/typescript/ に保持されています。サポートポリシーについては legacy/typescript/DEPRECATED.md を参照してください。

ライセンス

Apache-2.0。