Comet Opik MCP Server

公式

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

ドキュメント

opik-mcp

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

Opik + Ollie 用 Model Context Protocol サーバー。 AI ホスト (Claude Code、Cursor、VS Code Copilot、MCP Inspector) を Opik ワークスペースに直接接続します — トレースの読み取り、スコアの記録、プロンプトバージョンの保存、 Ollie への調査質問をすべてチャットから行えます。

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

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 クラウド / セルフホスト)	`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 [email protected]: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 docs を参照
質問は Comet community Slack へ

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

ライセンス

Apache-2.0。