Opik Mcp

リモート

comet.com開発ツール225今日更新

リポジトリ公式サイト

Opik Mcp について

Opik公式のMCPサーバーです。LLMの可観測性・評価プラットフォームOpikをAIコーディングクライアントから使うエンジニア向けに、トレースの確認、スコア記録、プロンプトの版保存を提供します。

主な機能

01Opikのトレースとプロジェクト情報の閲覧
02理由付きトレーススコアの作成
03プロンプトの版の保存
04対応するAIクライアントの設定

活用シーン

01プロジェクト内の失敗したトレースの検索
02チャットからトレースを採点
03修正したプロンプトの版を保存
04コーディングクライアントをOpikワークスペースに接続

MCP 対応

トレースやプロジェクトの閲覧、スコア作成、プロンプトの版保存など、Opikワークスペースの操作をMCPクライアントに公開します。Opik Cloudではホスト型のStreamable HTTPサーバーを使い、セルフホスト版とオープンソース版ではローカルのstdioサーバーを実行できます。

#typescript #generative-ai #mcp-server #modelcontextprotocol

設定

リモートサーバーはインストール不要です。クライアントを選んで設定をコピーするか、ワンクリックで導入できます。

エンドポイントhttps://www.comet.com/opik/api/v1/mcp

インストールコマンドをコピー

Claude CodeTerminalclaude mcp add --transport http opik https://www.comet.com/opik/api/v1/mcp

Cursor.cursor/mcp.json{"mcpServers":{"opik":{"type":"http","url":"https://www.comet.com/opik/api/v1/mcp"}}}Cursor で開く

VS Code.vscode/mcp.json{"servers":{"opik":{"type":"http","url":"https://www.comet.com/opik/api/v1/mcp"}}}VS Code で開く

Claude Desktopclaude_desktop_config.json{"mcpServers":{"opik":{"type":"http","url":"https://www.comet.com/opik/api/v1/mcp"}}}

Windsurf~/.codeium/windsurf/mcp_config.json{"mcpServers":{"opik":{"serverUrl":"https://www.comet.com/opik/api/v1/mcp"}}}

コマンドはターミナルで実行し、JSON は各クライアントの MCP 設定に貼り付けて再起動します。認可が必要なサーバーは初回接続時にログインを求めます。

パッケージ

pypiopik-mcp3.0.8stdio

ツール

詳細

翻訳後に原文が更新されています。最新の内容は原文をご確認ください。

Opik MCP Server

Comet が開発した、オープンソースの LLM オブザーバビリティおよび評価プラットフォーム Opik の公式 Model Context Protocol（MCP）サーバーです。 AI ホスト（Claude Code、Cursor、VS Code Copilot、Codex、opencode、または任意の MCP クライアント）を Opik ワークスペースに直接接続し、チャットからトレースの読み取り、スコアの記録、プロンプトのバージョン保存を行えます。

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

You:    "Which traces in project 'demo' failed today?"
Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"

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

クイックスタート

1 つのコマンドで、お使いのマシン上の AI クライアントに Opik をセットアップできます。Claude Code も対象です。Opik（~/.opik.config に保存されているもの、localhost で実行中のもの、またはどれを使うか尋ねます）を検出して、MCP サーバーを登録し、Opik スキルパックをインストールして、接続を確認します。Opik Cloud では API キーを扱う必要はありません。クライアントがブラウザーでサインインします。uv が必要ですが、Opik SDK は必要ありません。

uvx opik@latest mcp configure

コーディングエージェントやスクリプトからなど、ターミナルを使わずに実行する場合は、クライアントを指定します。

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client には codex、cursor、vscode、opencode も指定できます。この方法で実行すると、 ~/.opik.config に保存されている Opik（API キーを含む）か、localhost で応答している Opik を使います。それ以外の場合は停止し、--deployment を指定するよう求めます。

「install opik mcp」と依頼されたコーディングエージェントは、ユーザーに何を尋ねるかも含めたすべての手順を uvx opik-mcp@latest --help から取得します。手順は、以下のコーディングエージェントを使ったインストールと同じです。

手動でのセットアップにあるクライアント別のコマンドを使ってサーバーを手動で登録すると、使用する Opik の確認とスキルパックのインストールは省略されます。そのため、インストーラーがサポートしていないクライアント向けの方法です。

お使いの Opik	サーバー	トランスポート	サインイン
Opik Cloud（`www.comet.com`）	ホスト型サーバー、Comet が運営	Streamable HTTP	ブラウザーで（OAuth）。API キー不要
セルフホストの Comet、オープンソース Opik	ローカルサーバー、このパッケージ	stdio	環境変数。デプロイで必要な場合のみ API キー

クライアントはセッション開始時に MCP サーバーを読み込むため、セットアップ後は新しいセッションを開始してください。

セットアップガイド、トラブルシューティング、よくある質問：comet.com/docs/opik/mcp-server。

Opik Cloud：ホスト型サーバー

Comet は https://www.comet.com/opik/api/v1/mcp でサーバーを運営しています。クライアントは HTTP 経由で接続し、初回はブラウザーでサインインします。インストールも API キーもワークスペースの設定も必要ありません。サーバーはサインイン時に選択したワークスペースで動作します。追加した後は新しいセッションを開始し、 **「Opik のプロジェクトを一覧表示して」**と尋ねてください。

クイックスタートコマンドを使うと、スキルパックとともに Claude Code、Codex、 Cursor、VS Code Copilot、opencode をセットアップできます。以下のボタンから Cursor または VS Code にワンクリックで追加できます。手動で登録するその他の方法は手動でのセットアップにあります。

セルフホスト可能なオープンソースの Opik：ローカルサーバー

opik-mcp はマシン上で実行されます。クライアントが uvx opik-mcp で起動し、stdio 経由で通信します。クイックスタートのコマンドは、~/.opik.config またはローカルの Opik から設定します。手動で登録する場合は、手動でセットアップするを参照してください。uv を一度インストールすれば、初回使用時にパッケージと、必要に応じて Python 3.13 を取得します。

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

uvx opik-mcp は uv がキャッシュしたコピーを再利用するため、すばやく起動します。uv cache clean opik-mcp を実行すると、次回の起動時に最新リリースを取得します。uvx opik-mcp@latest は起動のたびに PyPI に問い合わせるため、約 1.5 秒余分にかかります。Codex は最初のツール一覧を作成する前に、サーバーを待つ時間として mcp_optional_startup_grace_ms（デフォルトでは 1 秒）を設定しています。そのため、起動が遅いと最初のターンではツールが含まれないことがあります。この README に記載されている単発コマンド（opik mcp configure、opik mcp status、--help、--check）には @latest が付いているため、uv が数か月前にキャッシュしたコピーが実行されることはありません。

環境変数でサーバーの接続先 Opik を指定します。

利用する Opik	環境変数
このマシン上のオープンソース版 Opik	`OPIK_URL=http://localhost:5173/api`
サーバー上のオープンソース版 Opik	`OPIK_URL=https://<host>/api`。デプロイで認証を追加している場合のみ、`OPIK_API_KEY` も指定します
セルフホスト版 Comet プラットフォーム（Opik UI は `https://<host>/opik`）	`COMET_URL_OVERRIDE=https://<host>`、`OPIK_WORKSPACE`、`OPIK_API_KEY`

オープンソース版は API を /api で提供し、ワークスペースは default の 1 つだけなので、OPIK_WORKSPACE は不要です。COMET_URL_OVERRIDE を指定すると、サーバーの接続先が /opik/api になりますが、オープンソース版はそこでは API を提供していません。
セルフホスト版 Comet には名前付きワークスペースがあります。OPIK_WORKSPACE には、Opik の URL で /opik/ の後に続く部分を指定します。省略した場合、読み取りはアカウントのデフォルトワークスペースから行われますが、そのことを示すエラーは表示されません。
MCP OAuth サーバー（デフォルトでは無効）を実行しているセルフホスト版 Comet では、代わりに https://<host>/opik/api/v1/mcp のホスト型フローを利用できます。
値はすべて置き換えてください。サーバーは <your-workspace> や ${input:OPIK_WORKSPACE} のようなプレースホルダーワークスペースを拒否します。プレースホルダー URL はそのまま送信され、接続に失敗します。
env ブロックに OPIK_MCP_ANALYTICS_SOURCE="" を指定すると、セルフホスト環境のテレメトリーイベントにクラウド Comet のソースラベルが付かなくなります。

サーバーをクライアントに追加する前に、設定を確認してください。同じ環境変数を指定して --check を付けて実行します。Opik に 1 回問い合わせて、ワークスペースと検出されたプロジェクト数を出力します。問題がある場合は、ドキュメントへのリンクと修正方法を出力し、0 または 1 で終了します。新しいセッションを開始する前にクライアントからこれを確認することはできません。Claude Code はキーが間違っていても「接続済み」と表示し、Codex はこの時点まで何も起動しません。

OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check

その後、クライアントに登録します：ローカルサーバー（セルフホスト可能なオープンソースの Opik）を手動で設定する。

コーディングエージェントでインストールする

「install opik mcp」のように、サーバーのインストールを依頼された AI エージェント向けです。目標は、ユーザーの Opik 用にサーバーを登録し、Opik スキルパックをインストールして、ユーザーのサインインを完了することです。このマシンの情報から使用する Opik を特定し、判断できないことだけをユーザーに尋ねてください。質問は 1 メッセージにつき 1 つとし、次の質問をする前に回答を待ちます。ステップ 3 のインストーラーは 1 回の実行でセットアップ全体を行うため、実行前にステップ 1 と 2 を済ませてください。uvx opik-mcp@latest --help を実行すると、これらのステップが表示されます。

現在の状況を確認します。
```
uvx opik@latest mcp status
```
~/.opik.configに保存されているOpik（URLとワークスペース。キーは表示されません）と、すでにサーバーが設定されているクライアントが表示されます。Claude Codeでは、claude mcp listも実行してください。claude.aiコネクターや、ほかの名前で登録されたエントリーが表示されます。また、各エントリーのコマンドも出力されます。古いnpxエントリーにはAPIキーが含まれている場合があるため、繰り返し表示しないでください。
- 名前を問わず、https://www.comet.com/opik/api/v1/mcpのサーバーが登録されていれば（claude.aiコネクターなど）、すでに設定済みです。重複して追加しないでください。スキルパックだけをnpx skills add comet-ml/opik-skills -g --allでインストールしてください。サーバーに! Needs authenticationと表示される場合は、手順4に進んでください。
- インストーラーは、古いnpxサーバー用のものなど、既存のopik-mcpエントリーを確認なしで置き換えます。実行する前にユーザーに確認してください。
ユーザーが利用しているOpikを確認します。
- ~/.opik.configに保存されている場合：それを使用し、どのOpikを設定するかユーザーに伝えてください。インストーラーはAPIキーを含めてこの設定を読み込むため、キーを尋ねる必要はありません。
- ~/.opik.configがない場合：curl -s http://localhost:5173/api/is-alive/pingを実行します。応答があれば、このマシン上のオープンソース版Opikです。Codexのようなサンドボックス化されたシェルでは、応答がないのはOpikがないのではなく、シェルにネットワークアクセスがないためかもしれません。
- どちらにも該当しない場合：ユーザーに確認し、自分で決めないでください。.env内のOPIK_URL_OVERRIDEのようにプロジェクトにOpik URLが設定されている場合は、「はい」か「いいえ」で答えられる質問にします。それ以外の場合は、次のように尋ねてください：「どのOpikを利用していますか？Opik Cloud（www.comet.com）、オープンソース版Opik（URL）、またはセルフホスト型Cometプラットフォーム（URLとワークスペース）のどれですか？」

使用するクライアント向けにインストーラーを実行します。 Opikのスキルパックは、--skillsの有無にかかわらずサーバーと一緒にインストールされます。後でユーザーに実行してもらうコマンドにも、このフラグを残してください。Opik Cloudではブラウザーでサインイン画面が開き、インストーラーはそのまま1分間待機するため、先にユーザーに伝えてください。

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-clientには、codex、cursor、vscode、opencodeも指定できます。Opikが~/.opik.configに保存されている場合、またはローカルホストで実行中の場合は、そのまま実行してください。--deploymentを指定すると、APIキーを含む保存済み設定は使用されません。どちらにも該当しない場合は、手順2でユーザーが指定したOpikに応じて、次のフラグを追加してください。

ユーザーが利用しているOpik	追加する内容
Opik Cloud、`www.comet.com`	`--deployment cloud`
オープンソース版Opik	`--deployment local`。ローカルホスト以外で実行されている場合は`--url <url>`も追加
セルフホスト型Cometプラットフォーム。URLに`/opik/`が含まれる場合	`--deployment self-hosted --url <url> --workspace <workspace>`を指定し、シェルに`OPIK_API_KEY`を設定

Opikから応答がない場合など、失敗したときは、出力された内容と、VPNやURLなど確認すべき項目をユーザーに伝えてください。別のOpikに切り替えないでください。

Opik Cloudへのサインイン。 インストーラーからサーバーがまだサインインしていないと報告された場合、claude mcp login opik-mcpを実行するか、Claude Codeのセッションで/mcpを実行するようユーザーに案内してください。ブラウザーでの操作を待つため、自分で実行しないでください。claude.aiコネクターは/mcpからサインインします。サインイン時にワークスペースを求められた場合は、~/.opik.configに保存されていれば、その名前を指定してください。
完了。 インストールしたものと、残っている作業を伝えてください。スキルパックの名前も明記してください。Opikスキルはすべてのプロジェクトにインストールされ、エージェントがOpikを使って計測、評価、デバッグを行う方法を学習します。クライアントはセッション開始時にMCPサーバーとスキルを読み込むため、新しいセッションを開始してから、**「Opikのプロジェクトを一覧表示して」**と試すようユーザーに案内してください。

どの場合も：

ユーザーにチャットへ API キーを貼り付けるよう求めないでください。ホスト型サーバーでは API キーは不要です。それ以外の場合は、シェル環境（"$OPIK_API_KEY"）から取得するか、ユーザー自身にコマンドを実行してもらってください。
ワークスペースを推測しないでください。ユーザーの Opik URL で、comet.com/opik/（セルフホスト型 Comet の場合は /opik/）の後に続く部分がワークスペースです。
~/.claude.json や ~/.opik.config を表示しないでください。どちらにも API キーが含まれている可能性があります。必要な情報は uvx opik@latest mcp status と claude mcp list で確認でき、インストーラーは設定を直接読み取ります。
権限チェックによってコマンドがブロックされた場合、回避しないでください。ユーザーに実行するコマンドを提示してください（Claude Code では、実行前にプロンプトの先頭に ! を付けます）。

インストーラーが対応していないクライアントの場合は、手動で設定するにあるコマンドを使って手動で登録してください。Opik Cloud ではホスト型サーバーを、それ以外ではローカルサーバーを使用します。

ローカルサーバーを登録する前に、渡す環境変数を設定し、シェルで OPIK_API_KEY をエクスポートして、コマンドには記述せずに --check を付けて実行してください： OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check。終了コード 0 で検出したワークスペースが表示されるか、修正すべき内容が出力されます。登録後、キーが間違っていても Claude Code では Connected と表示され、Codex にはチェック機能がありません。
Claude Code では既存の opik-mcp エントリに上書きできないため、先に claude mcp remove opik-mcp --scope user で削除してください。Codex では add が既存の設定を置き換えます。
登録後、Claude Code ではステータス行だけを確認してください： claude mcp get opik-mcp | grep Status。出力全体には API キーを含む env ブロックが表示されます。ホスト型サーバーは、claude mcp login opik-mcp を実行するまで ! Needs authentication と表示されます。Codex にはセッション開始前にサーバーを起動する機能がありません。codex mcp get opik-mcp では、保存された内容を確認でき、環境変数の値はマスクされます。

手動で設定する（Opik の確認なし、スキルパックなし）

クイックスタートコマンドは、Claude Code、Codex、 Cursor、VS Code Copilot、opencode に対してこれらすべてを実行し、使用中の Opik も確認してスキルパックをインストールします。別のクライアントを使う場合や、インストーラーが書き込む内容を確認する場合にのみ、手動で登録してください。ユーザーに代わってコーディングエージェントがインストールする場合は、インストーラーを実行してください。コーディングエージェントを使ったインストールを参照してください。

ホスト型サーバー（Opik Cloud）

Claude Code（手動）

claude mcp add --scope user --transport http opik-mcp https://www.comet.com/opik/api/v1/mcp

その後、Claude Code のセッションで /mcp → Authenticate を選択してサインインします。ブラウザーが開くため、キーボードの前にいる人が操作します。本人の端末から claude mcp login opik-mcp を実行しても同じです。--scope user を指定すると、すべてのプロジェクトでサーバーを使用できます。指定しない場合、Claude Code は現在のディレクトリにのみ登録します。SSH 経由の場合、claude mcp login opik-mcp --no-browser を実行すると、手元のマシンで開くサインイン URL が表示されます。最後の手順には対話型ターミナルが必要です（ssh -t）。

Codex（手動）

codex mcp add opik-mcp --url https://www.comet.com/opik/api/v1/mcp

add を実行するとサインイン画面が開きます。codex mcp login opik-mcp を実行しても、もう一度開けます。~/.codex/config.toml での同じサーバーの設定は次のとおりです：

[mcp_servers.opik-mcp]
url = "https://www.comet.com/opik/api/v1/mcp"

Cursor（手動）

ホスト型サーバーの下にあるボタンを使うか、~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "opik-mcp": {
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

VS Code Copilot（手動）

ホスト型サーバーの下にあるボタンを使うか、ワークスペース内の .vscode/mcp.json またはユーザーの mcp.json（MCP: Open User Configuration）に追加します：

{
  "servers": {
    "opik-mcp": {
      "type": "http",
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

その他のクライアント

URL を指定できるクライアントであれば、ホスト型サーバーを使用できます：

npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp

ローカルコマンドしか起動できないクライアントは、npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp 経由で接続できます。

API キーを使用した Opik Cloud

スクリプトからエージェントを無人で実行する場合や、クライアントが MCP OAuth をサポートしていない場合など、ブラウザーでのサインインを完了できない環境では、代わりに comet.com/api/my/settings/ の API キーを使用し、ローカルサーバーの接続先を Opik Cloud に設定します。

claude mcp add --scope user opik-mcp \
  --env OPIK_API_KEY="$OPIK_API_KEY" \
  --env OPIK_WORKSPACE=<workspace> \
  -- uvx opik-mcp

ほかのクライアントでも、同じ 2 つの変数を env ブロックに指定します。 OPIK_WORKSPACE には、Opik URL の comet.com/opik/ の後に続く部分を設定します（https://www.comet.com/opik/acme-ai/projects → acme-ai）。省略すると、サーバーは default を送信し、Comet はこれをアカウントのデフォルトのワークスペースとして扱います。そのため、エラーにならないまま、誤ったワークスペースからデータを読み込む可能性があります。

ローカルサーバー（セルフホスト可能なオープンソースの Opik）

以下の例では、ローカルのオープンソース版 Opik を使用しています。セルフホスト版の Comet では、表にある 3 つの変数を設定してください。サーバーを追加したら、新しいセッションを開始し、 **「Opik プロジェクトの一覧を表示して」**と尋ねます。

Claude Code の手動設定

claude mcp add --scope user opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

セルフホスト版の Comet で、シェルの OPIK_API_KEY にキーを設定している場合：

claude mcp add --scope user opik-mcp \
  --env COMET_URL_OVERRIDE=https://<host> \
  --env OPIK_WORKSPACE=<workspace> \
  --env OPIK_API_KEY="$OPIK_API_KEY" \
  -- uvx opik-mcp

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

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

サーバーが起動すると、claude mcp get opik-mcp に ✔ Connected と表示されます。これは URL やキーが正しいことの証明にはなりません。Opik に接続するのはツール呼び出しのときだけです。確認にはローカルサーバーの --check を使用してください。これを実行すると、API キーを含む env ブロックも出力されます。

Codex の手動設定

codex mcp add opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

または、~/.codex/config.toml を編集します。

[mcp_servers.opik-mcp]
command = "uvx"
args = ["opik-mcp"]
env = { OPIK_URL = "http://localhost:5173/api" }
# On a self-hosted Comet, forward the key from the environment Codex starts in,
# so it stays out of this file:
# env_vars = ["OPIK_API_KEY"]
# Time allowed for the server to start (default 10 s); the first start
# downloads the package.
startup_timeout_sec = 30

Codex がローカルサーバーに渡すのは、env 内の変数と env_vars 内の名前だけです。そのため、シェルでエクスポートしたキーは、そのままではサーバーに渡されません。

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_URL": "http://localhost:5173/api"
      }
    }
  }
}

Cursor の 60 秒タイムアウト。 Cursor には、進行状況の通知があってもリセットされない、厳格なツール呼び出しタイムアウトが設定されています。既知のホスト制限を参照してください。

VS Code Copilot の手動設定

ワークスペースの .vscode/mcp.json、またはユーザーの mcp.json（MCP: Open User Configuration）に追加します。

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

MCP Inspector（手動テスト）

OPIK_URL=http://localhost:5173/api npx @modelcontextprotocol/inspector uvx opik-mcp

`npx opik-mcp` をお使いの場合

TypeScript サーバー（npm opik-mcp@2）は非推奨となっており、2026-11-15 にリクエストの処理を停止します。新規インストールでは、クイックスタートのコマンドを実行してください。uvx opik-mcp は、クライアントがサーバーを起動するためのコマンドであり、インストーラーではありません。Opik Cloud を使用する既存の設定を移行する場合は、ホスト型サーバーに切り替えて API キーを削除してください。それ以外の場合は、MCP クライアントの設定で npx -y opik-mcp を uvx opik-mcp に置き換えます。一部の環境変数は名前が変更され、コマンドラインフラグは読み込まれなくなりました。詳しくは移行ガイドを参照してください。サポートポリシーについては、DEPRECATED.mdを参照してください。 TypeScript のソースは git タグ legacy-typescript-final にあります。

ツール

opik-mcp は、ライフサイクル全体（読み取り → 注釈付け → キュレーション → 作成 → 反復）を網羅する、成果重視のシンプルなインターフェースを提供します。

ツール	用途
`read`	ID／名前／`opik://` URI による汎用読み取り
`list`	任意の名前フィルターとページネーションに対応した汎用一覧表示
`write`	汎用書き込み — トレース／スパンのログ記録、スコア付け、コメント、プロンプトの保存、データセットと実験の管理
`schema`	書き込み操作のスキーマを調査します（LLM が有効なペイロードを構築するために使用）
`read_skill`	このサーバーにバンドルされている Opik エージェントスキルの 1 つを読み取ります

`read`

あらゆる「X を表示して」という質問に対応するツールです。entity_type と、ID（UUID または、名前を指定できる型の場合は名前）、あるいは完全な opik:// URI を指定します。複合読み取り（trace、prompt、thread、agent_insights_issue）では子要素もインラインで含めるため、1 回の呼び出しで全体像を取得できます。指定したレコードは完全な状態で返されます。インライン表示される子レコードはそうではありません。本文はバックエンドの truncate=true を使って取得されるため、ClickHouse では約 10 KB を超えるフィールドが切り詰められ、base64 画像は "[image]" に置き換えられます。添付ファイルが 200 個のスパンで繰り返し表示されると、読み取りのほかのすべてを上回るコストがかかるためです。回答では spanBodies / messageBodies にその旨が示されます。また、子レコード自体は read("span", id) または read("trace", trace_id) で再び完全な状態で取得できます。これらは truncate パラメーターを持たないエンドポイントにアクセスします。

インライン表示されるコレクションの長さにも上限があります。スパンは 200 件、ターンは 200 件、プロンプトのバージョンは 100 件です。上限を超えると spansTruncated / messagesTruncated / versionsTruncated が true になり、その横の moreSpans / moreMessages / moreVersions の行に件数と、インライン表示が止まった位置から続けるための正確な list(...) 呼び出しが示されます。

対応エンティティ： project、trace、span、dataset、dataset_item、experiment、prompt、thread、agent_insights_issue。名前による検索は project、experiment、prompt、dataset で利用できます（API 呼び出しが 2 回必要なため遅く、複数の一致が返る場合があります）。thread と agent_insights_issue はプロジェクトに紐付いています。project_id または project_name、あるいはプロジェクト情報を含むリンク／URI を渡してください。dataset と dataset_item は以前は test_suite と test_suite_item という名前でした。旧名でも引き続き解決されますが、案内には表示されず、新しいコードでは新しい名前を使ってください。

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")  # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
read(entity_type="agent_insights_issue", id="<issue-uuid>", project_id="<project-uuid>")
read(
    entity_type="agent_insights_issue",
    id="https://www.comet.com/opik/<ws>/projects/<pid>/diagnostics?issue=<id>",
)

Opik UI からコピーしたリンクは id として使用できます。スレッドのリンクまたは Diagnostics ページのリンクにはプロジェクト情報が含まれるため、project_id は不要で、エンティティの種類もリンクから判定されます。

project の読み取りでは、「プロジェクトの状況はどうなっていますか」という問いに 1 回の呼び出しで答えられます。{project, summary, vocabulary, contains, url} が返されます。レコードに続いて、Logs ページでカードとして表示される 4 つの指標（トレース数、エラー率、平均所要時間、合計コスト）が含まれます。期間は直近 7 日間とその前の 7 日間で、画面表示と同様に SDK トラフィックのみが対象です。since / until で期間を変更できます。UI を開いたときの期間は since="30d" です。トレースがない期間の率や平均は null で返されます。トラフィックがない週のエラー率を 0％とすると、健全な週のように見えてしまうためです。

vocabulary は、そのほかの情報を取得する前に必要となるマップです。プロジェクトのフィードバックスコア名、トークン使用量のキー、トレースを評価する自動化ルールが含まれます。以下のフィルターや series= に指定するのはこれらの名前です。推測した名前を指定すると空のページが返り、問題がないように見えてしまいます。スコア名とルールの表示数には上限がありますが、常に正確な合計件数と、残りを取得する呼び出しが示されます。使用量のキーは、ほかに列挙する方法がないため、すべて表示されます。contains には最新の実験、データセット、プロンプトのバージョン、最適化実行が含まれるため、「ここで何が起きているのか」を知るために、さらに 4 回呼び出す必要はありません。読み込みに失敗した項目にはその旨が示され、空のようには見えません。空の項目は省略されます。

agent_insights_issue の読み取りでは {issue, example_trace_ids, details} が返されます。Diagnostics のイシューレコード（名前、説明、原因、推奨される修正、重大度、ステータス）、該当するトレースの重複を除いた ID（Diagnostics ページに表示されるものと同じサンプルです。1 つを read("trace", id) で開けます）、および日ごとの内訳が含まれます。トレースの本文はインライン表示されないため、読み取りはバックエンドへの呼び出し 1 回で済みます。since / until で日ごとの行を絞り込めます。デフォルトでは全期間が対象です。サーバーが Opik URL とセッションのワークスペースを把握している場合、読み取りには url（イシューの Diagnostics ページ）と trace_url_template（サンプルトレースへのディープリンク）も含まれるため、アシスタントはクリック可能なリンクを提示できます。ワークスペースを特定できなかった OAuth セッションでは、リンクは推測せず省略されます。トレース自体には URL がありません。read や list が返すフィールドからリンクを導き出すことはできず、形を推測しても 404 になります。代わりに、セッションの指示でテンプレートが示されます。 .../v1/session/redirect/projects/?trace_id={trace_id}&path=...。そのため、アシスタントが ID を埋めてリンクを渡せます。このリンクは opik-backend のリダイレクトを経由し、トレースからプロジェクトとワークスペースを解決するため、プロジェクトの直接 URL では機能しない場合でも使えます。ワークスペースが未解決の OAuth セッションも含まれます。これは、Python SDK がトレースに対して表示するものと同じリンクです。

`list`

ページネーションを使ってコレクションを閲覧または検索します。プロジェクトにスコープされるタイプ（trace、span、thread、agent_insights_issue、dataset_item、prompt_version）には、親にあたるプロジェクトの UUID または名前、データセットの UUID、あるいはプロンプトの UUID が必要です。

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")  # name substring filter
list(entity_type="agent_insights_issue", project_name="demo")  # open Diagnostics issues
list(entity_type="agent_insights_issue", project_id="<uuid>", status="resolved")
list(entity_type="trace", project_name="demo")  # latest traces of one project
list(
    entity_type="trace", project_name="demo", filters="error_info is_not_empty AND duration > 5000"
)
list(
    entity_type="span",
    project_name="demo",  # spans across the whole project
    filters='type = "llm" AND usage.total_tokens > 10000',
)
list(
    entity_type="thread",
    project_name="demo",
    filters="number_of_messages > 20 AND feedback_scores.helpfulness < 0.5",
)
list(entity_type="experiment", filters='dataset_id = "<dataset-uuid>" AND tags contains "baseline"')

フィルター。 trace、span、thread、experiment、dataset_item では、SDK の search_traces(filter_string=…) と同じ文法の OQL 文字列を指定します。

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

文字列は二重引用符で囲み、数値はそのまま記述します。duration の単位はミリ秒です。日付はタイムゾーンを含む ISO-8601 形式の時刻です（"2026-09-08T10:00:00Z"）。スコアと辞書はキーを指定します。例：feedback_scores.accuracy < 0.5、metadata.environment = "prod"。接続子として使用できるのは AND のみです。

UI の Logs ページと同様に、トレース、スパン、スレッドのリストでは source = "sdk" が追加され、評価、プレイグラウンド、実験のトレースが表示されないようになっています。これらを表示するには、source を自分で指定してください。最初の出力行には、適用されたフィルターが表示されます。

不正なフィルターはバックエンドに到達する前にエラーとなり、修正に必要な情報が示されます。構文エラーの位置、最も近いフィールド名、そのフィールドの型で有効な演算子、または期待される値の形式です。値の種類が限定されているフィールド（source、span の type、thread の status、visibility_mode）も照合されます。in リストの各要素も対象です。source はバックエンド自身が検証する唯一の項目で、未知の値に対して 400 ではなく 500 を返します。そのため、source = "SDK" は大文字が含まれることで、通常は原因の分からないサーバーエラーになります。ほかの項目は文字列として比較されるため、「その値は存在しない」という意味でも空のページが返り、「一致するものがない」と解釈されます。全フィールドのリファレンスと有効な値については、schema("list.trace")（または list.span、list.thread、list.experiment）を確認してください。

データセット内のケースを見つける。 list(entity_type="dataset_item", dataset_id=…) はケースそのものを対象にフィルターします。データセットの作成時に使ったキーには data.<key>、ペイロード全体の部分文字列には full_data を使います（全件スキャンのため、可能ならキーを指定してください）。さらに、id、tags、source、trace_id、span_id、タイムスタンプでもフィルターできます。data.<key> で使えるのは 6 つの文字列演算子（=、!=、contains、not_contains、starts_with、ends_with）のみです。比較を行うとバックエンドが 400 を返すため、この指定は呼び出し前に拒否されます。このエンドポイントには並べ替え機能もフリーテキスト検索もありません。sort は無視されるのではなく、拒否されます。テーブルで省略された値を読み取るには、read(entity_type="dataset_item", id=…) を使うと、1 つのケース全体が返されます。

list(entity_type="dataset_item", dataset_id="<uuid>", filters='data.question contains "install"')
list(
    entity_type="dataset_item", dataset_id="<uuid>", filters='trace_id = "<trace-uuid>"'
)  # the case made from that trace
read(entity_type="dataset_item", id="<item-uuid>")  # the case, uncut

experiment_ids を指定すると、同じリストが比較対象になります。各実行が紐付いたケースを対象に、実行の情報（feedback_scores.<name>、output、duration）でフィルターします。対象となるフィールドセットは異なり、バックエンドのエンドポイントも別です。データセット独自のケースには schema("list.dataset_item_case")、比較には schema("list.dataset_item") を使います。

並べ替え。 trace、span、thread、experiment では sort="<field> [asc|desc]" を指定できます。既定値は desc で、フィールドは 1 つのみです。例：sort="duration desc"、sort="total_estimated_cost"、sort="feedback_scores.accuracy asc"、sort="usage.total_tokens"。バックエンドは並べ替えできないフィールドを黙って無視するため、呼び出し前にフィールドがエンティティの並べ替え可能なフィールド一覧に含まれているか確認されます。非常に大きなワークスペースではバックエンドが並べ替えを完全に省略することがあり、その場合はヘッダーに表示されます。 dataset_item は比較対象（experiment_ids）としてのみソートします。items エンドポイントはソートパラメーターを受け取らないため、通常の一覧に対するソートは無視せず拒否します。

時間範囲と検索。 trace、span、thread は since と until を受け取ります。どちらも相対的な期間（"30m"、"1h"、"7d"）またはタイムゾーン付きの ISO-8601 形式の時刻を指定できるため、「直近1時間」を調べるために時刻を計算する必要はありません。時間範囲にはレコードの作成時刻を使用します。これはバックエンドでの処理コストが低く、ライブトラフィックでは数秒以内の差で start_time と一致します。厳密な境界を指定するには、filters に start_time を設定してください。同じ3つの型は search も受け取り、id、name、input、output、metadata、tags、thread id のいずれかに一致する自由形式のテキストを検索します。検索ではバックエンドがプロジェクト全体をスキャンするため、大規模なプロジェクトでは最初の呼び出しに数十秒かかる場合があります。これらの呼び出しには60秒のタイムアウトが設定されています。since を追加すれば、再び高速になります。

テーブルの読み方。 期間は duration_ms ／ ttft_ms と表示され、ミリ秒単位の整数で示されます。filters と sort ではフィールド名は duration のままです。タイムスタンプは秒単位で表示され、コストは小数のまま表示されます。プロジェクト行には last_updated_trace_at が含まれるため、どのプロジェクトにライブトラフィックがあるかを確認できます。スレッド行には最初のメッセージが含まれます。時間範囲を指定したときにページが空の場合は、プロジェクトに最後のトレースが届いた時刻を示します。デフォルトの source = "sdk" を指定したときにページが空の場合は、ほかのソースを確認する方法を示します。スペルミスのある project_name を指定すると、最も近い既存の名前が返されます。

list(
    entity_type="trace",
    project_name="demo",
    since="1h",
    filters="error_info is_not_empty",
    sort="duration desc",
)
list(entity_type="trace", project_name="demo", search="order-42")

診断の問題。 agent_insights_issue は MCP 経由で Diagnostics ページを表示します。これは、Opik の Diagnostics ジョブがプロジェクト内で繰り返し発生する障害をグループ化したもので、UI と同じ順序（最後に確認されたものが先）で並びます。列は severity、status、total_occurrences（全期間の合計）、latest_count（最新のレポート日の件数で、問題自体の説明に記載される数値）、last_seen です。デフォルトでは未解決の問題が一覧表示されます。残りの問題を表示するには、status="resolved" または "closed" を渡してください。read と list は issue という名前でも応答します。これは UI での呼び名です。長い名前は entity_type enum で使われるもので、同じエンティティがそこに重複して表示されることはありません。件数は UI と一致するよう全期間の値です。トレースと同じ since ／ until を指定すると、Diagnostics は日ごとに集計するため、時間範囲は UTC のレポート日単位に切り捨てられます。

一覧が空の場合は、その理由が示されます。「問題がない」場合と「Diagnostics が有効になっていない」場合は、そうしなければ同じように見えるためです。状態は5種類あります。このデプロイでは Diagnostics を利用できない、このプロジェクトでは有効になっていない、無効になっている、Diagnostics は有効だが最近スキャンされていない、または有効で問題がなく最後にスキャンした時刻が示される、のいずれかです。対応できる状態では、実行すべき呼び出しが示され、どの状態でもプロジェクトの Diagnostics ページへのリンクが表示されます。

一覧が空でない場合は、対象期間が示されます。問題は直近のスキャンでグループ化されたものなので、応答の末尾には Report covers data through <time> が表示されます。指定した時間範囲がその時刻より先まで続く場合は、未集計の期間と、それを確認する方法が示されます。再スキャンが十分に過去までさかのぼった場合はトリガーを使い、それ以外の場合は指定された since を使って生のトレースを確認します。毎晩スキャンされるプロジェクトで1週間を指定すると、グループ化された結果には最終日のデータが含まれません。そのことがここに示されます。

write("agent_insights_job.enable", {"project_name": "demo"}) は Diagnostics を有効にします。それ以降は毎日スキャンが実行され、再度呼び出しても問題ありません。 write("agent_insights_job.trigger", …) は夜間の実行を待たずに、直近24時間を今すぐスキャンします。どちらも問題の読み取りと同じ権限が必要で、デプロイで Diagnostics が利用できない場合は拒否されます。課題のライフサイクルを進めるには、 write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) で対処済みにするか、対応する価値がない場合は …close でクローズし、どちらも …reopen でオープンの一覧に戻します。3つの操作はすべて同じ権限が必要で、課題が移動した先のビューへのリンクを返します。解決済みの課題はデフォルトページに表示されなくなるためです。障害が修正されたかどうかは判断が分かれるため、これらの操作は依頼されたときに使います。アシスタントがトリアージ中に勝手に一覧を整理するべきではありません。

時間の経過に伴うメトリクス。 project_metric は、プロジェクトの1つのメトリクスを期間ごとの集計表として表示します。対象は、トレース、スパン、スレッドの数、期間、エラー率、コスト、トークン使用量、フィードバックスコアです。概要の次に尋ねられる「何が変わったのか」という質問に答えます。

list(entity_type="project_metric", project_name="demo", metric_type="trace_count")
list(
    entity_type="project_metric",
    project_name="demo",
    metric_type="trace_error_rate",
    since="14d",
    interval="daily",
)
list(
    entity_type="project_metric", project_name="demo", metric_type="span_count", breakdown="model"
)  # one column per model
list(
    entity_type="project_metric",
    project_name="demo",
    metric_type="span_duration",
    breakdown="model",
    series="p99",
)  # the p99 of each model

各行はレコードではなく期間ごとの集計なので、page、size、sort は無視されず、拒否されます。interval は hourly、daily、weekly、total のいずれかです。省略すると、Metrics タブと同様に期間に応じて選ばれます。3日までは時間単位、30日までは日単位、それ以上は週単位となるため、デフォルトのグラフは期間にかかわらず数十行に収まります。月単位の時間別データ（721行）が必要な場合は、そのように指定してください。since／until はほかのすべての箇所と同じ形式で指定でき、省略すると直近7日間になります。filters では、メトリクスの対象エンティティのフィールドを使います。そのため、スパンメトリクスはスパンのフィールドでフィルタリングされます。

breakdown は各期間の集計を tags、name、error_info、error_type、model、provider、span_type、guardrail_name、metadata.<key> で分類します。すべてのメトリクスがこれらすべてに対応しているわけではなく、分類に対応しないメトリクスも7つあります。どれが使えるかはツールが把握しており、バックエンドを呼び出す前に通知します。同じ質問に答えられる別のメトリクスがある場合は、その名前も示します。3つの系列では複数の系列が同時に返されます（期間では p50／p90／p99、フィードバックスコアでは名前ごと、トークン使用量ではキーごと）。グループ化する場合、バックエンドは一度に1つの系列をグラフ化するため、series= でパーセンタイル、スコア名、使用量キーのいずれかを選びます。期間はデフォルトで p50、トークン使用量は total_tokens となり、使用された値は最初の行に表示されます。

データのない期間は省略され、その数が下に表示されます。そのため、静かな月はゼロが並ぶ列ではなく数行で示され、トレースがない期間の率はゼロではなく、値なしとして扱われます。

メトリクスの一覧、期間、およびメトリクスごとの分類対応表を確認するには、schema("list.project_metric") を呼び出します。

プロジェクトの名前。 score_name はプロジェクトに記録されたフィードバックスコアの名前を、online_rule はプロジェクトに設定された自動化ルールの評価器を一覧表示します。これらの評価器は、そうした名前の多くが由来するものです。どちらも read("project", …) に含まれるものと同じ一覧を、すべてページネーション付きで返します。概要にある上限付きの一覧では不十分な場合に使えます。

list(entity_type="score_name", project_name="demo")
list(entity_type="online_rule", project_name="demo")

`write`

汎用的な書き込みディスパッチャーです。operation と data を渡すと、ディスパッチャーがペイロードを検証し、適切な REST 動詞を適用して、バックエンドの応答を返します。

操作：

操作	内容
`trace.create`	単一のトレース（または一括）を記録します。スパン／スコア／コメントの親となります。
`trace.update`	既存のトレースを完了または修正します。
`span.create`	既存のトレースにスパンを記録します（または一括）。
`score.create`	トレース、スパン、またはスレッドに数値のフィードバックスコアを追加します。
`comment.create`	トレース、スパン、またはスレッドに自由形式のコメントを追加します。
`prompt_version.save`	新しいプロンプトバージョンを保存します（指定した名前のプロンプトが存在しない場合は作成します）。
`dataset.create`	データセットを作成します — `type: "test_suite"` を指定すると、評価用テストスイートになります。
`dataset_item.upsert`	データセットにアイテムをアップサートします（常にエンベロープ形式を使用します）。
`experiment.create`	データセットに関連付けられた実験を作成します。
`experiment_item.create`	トレースと dataset_item の行を実験に追加します。
`thread.close`	スレッドを閉じます（非アクティブとしてマークします）。`thread_id` とプロジェクトを渡します。
`thread.open`	閉じたスレッドを再開します。`thread_id` とプロジェクトを渡します。
`agent_insights_job.enable`	プロジェクトの Diagnostics を有効にします（毎日のスキャンを実行します。繰り返し実行しても安全です）。
`agent_insights_job.trigger`	過去24時間を対象に、Diagnostics スキャンを今すぐ実行します。
`agent_insights_issue.resolve`	Diagnostics の問題に対処済みのマークを付けます（先にユーザーに確認してください）。
`agent_insights_issue.close`	Diagnostics の問題に対応する価値がないとマークを付けます（先にユーザーに確認してください）。
`agent_insights_issue.reopen`	解決済みまたはクローズ済みの Diagnostics の問題を、オープンリストに戻します。

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

`schema`

書き込み操作を呼び出す前に、その正確な JSON 形式と必須フィールドを確認できます。data の形式が不明な場合に便利です。スキーマ、OAuth スコープ、検証済みの例を返します。参照のみで、バックエンドへの呼び出しは行いません。

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

同じツールは、list.trace、list.span、list.thread、list.experiment に対して、そのエンティティに対応する list ツールのリファレンスも返します。フィルター可能なすべてのフィールドとその型および有効な演算子、ソート可能なフィールド、時間範囲と全文検索を適用できるかどうか、2つのフィルター例が含まれます。

schema(operation="list.trace")

設定

これらはローカルサーバーの設定で、すべて環境変数です。Opik Cloud のホスト型サーバーでは、いずれも使用しません。

ID／エンドポイント

変数	デフォルト	備考
`OPIK_API_KEY`	—	セルフホスト版 Comet 用の API キー、またはホスト型サーバーを使わずに Opik Cloud を利用するための API キーです。オープンソース版 Opik では、デプロイ環境で認証を追加しない限り不要です。
`OPIK_WORKSPACE`	未設定	ワークスペース名です。API キーを使ったクラウド環境で未設定の場合は `default` が送信され、アカウントのデフォルトワークスペースに解決されます。別のワークスペースを使用する場合は明示的に設定してください。そうしないと、読み取りが誤ったワークスペースから行われても気づけません。OAuth 使用時（トークンに含まれます）と、ローカル／OSS 環境（使用できるワークスペースは `default` のみ）では未設定のままにしてください。
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` の非推奨エイリアス（後方互換性用）です。両方が設定されている場合は `OPIK_WORKSPACE` が優先されます。
`COMET_WORKSPACE_ID`	未設定	任意のワークスペース UUID です。設定すると分析イベントに記録され、解決されたワークスペース ID より優先されます。必要になることはほとんどありません。OAuth インストールでは、トークンから UUID が自動的に取得されます。
`COMET_URL_OVERRIDE`	`https://www.comet.com`	セルフホスト版 Comet のホスト、またはステージング用の `https://dev.comet.com` を設定します。
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api` から導出	API を `/api` で提供するオープンソース版 Opik 用に設定します（ローカル環境では `http://localhost:5173/api`）。Comet プラットフォームでは、Opik が Comet の UI とは異なるホスト／パスにある場合にのみ上書きしてください。
`OPIK_DEFAULT_PROJECT_NAME`	未設定	設定すると、セッションごとの `instructions` ブロブによって、ユーザーが別のプロジェクトを指定しない限り、すべてのツール呼び出しで LLM がこれを `project_name` として渡すよう指示されます。

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

変数	デフォルト	備考
`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 検出プローブのプロキシ先として使用されます。MCP ホストが HTTP 経由で OAuth フローを開始するために必要です。
`OPIK_MCP_RESOURCE_URI`	未設定	このサーバーの正規の公開 URI。保護リソースのメタデータで `resource` として公開され、`WWW-Authenticate` ヒントの導出に使用されます。
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	opik-backend のトークンイントロスペクションで「有効」と判定された結果を信頼し、同じ OAuth トークンを使った次のリクエストで再確認するまでの時間です。リクエストごとの検証によるバックエンド負荷と、期限切れトークンが転送される時間を制限します（この時間も、バックエンドが最初に 401 を返した時点で終了します）。バックエンドが `expires_at` を返す場合は、トークン自体の有効期限を上限とします。
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr ロガーのしきい値です。

トランスポートの選択

Bearer の形式が 2 種類あり、HTTP トランスポートの動作もそれぞれ異なります。opik_mcp_at_… OAuth アクセストークンは、リクエストごとに opik-backend のトークンイントロスペクションエンドポイントで検証されます（キャッシュの詳細は OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S を参照）。期限切れまたは失効したトークンには、WWW-Authenticate: Bearer error="invalid_token" を含む HTTP 401 が返されます。MCP ホストはこれを基に、ユーザーに知らせず refresh_token グラントを実行します。Opik API キーはローカルでは検証されず、そのまま opik-backend に転送されます。検証は opik-backend のみで行われます。デプロイ形態に応じてトランスポートを選択してください。

シナリオ	トランスポート
Opik Cloud	起動するものはありません。ホスト型サーバーは、Comet が実行するこのサーバーの HTTP 版です
MCP クライアントと Opik が同じマシン上にある場合（ローカル OSS インストール）	stdio（推奨 — 最も簡単で、ポートも OAuth の設定も不要です）
ローカル MCP クライアント → セルフホストの Opik	デプロイ用の環境変数を使った stdio、または OAuth を使った HTTP（`OPIK_MCP_AS_URL` はバックエンドを指定）
opik-mcp が opik-backend と同じエッジの背後で提供される場合	HTTP — Bearer はリクエストごとにバックエンドで検証されます

ローカル OSS インストールに関する注意：OSS バックエンドはリクエストを認証しないため、その前段に置かれた HTTP opik-mcp も、OSS REST API と同様に認証なしでアクセスできます。共有ネットワークでは、デフォルトの 127.0.0.1 バインドを維持し、stdio の使用を推奨します。

既知のホスト制限

ホストによって、1 回のツール呼び出しを実行できる時間は異なります。

Claude Code — ツール呼び出しのタイムアウトは文書化されていません。推奨です。
Cursor — 固定の 60 秒タイムアウトがあり、進捗があってもリセットされません (上流のバグ)。
MCP Inspector — MAX_TOTAL_TIMEOUT によって合計実行時間が制限されます（デフォルトは 60 秒）。長時間かかる操作では、Inspector UI で値を大きくしてください。

呼び出しが停止した場合は、OPIK_MCP_LOG_LEVEL=DEBUG を設定して、リクエストログ全体を確認してください。

トラブルシューティング

セットアップは正しく動作していますか？ クライアント設定の環境変数を使って、サーバーを--check付きで実行します：OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check。認識したワークスペースとプロジェクトを表示するか、修正が必要な内容を示します。サーバー自体のエラーにも、変更すべき内容と該当するドキュメントページへのリンクが記載されています。

OPIK_API_KEYが認識されない — 変数がサーバープロセスに渡されていません。Claude Code／Cursor／VS Codeでは、環境変数が適用されるのはシェル内ではなく、MCP サーバー設定のenvブロック内にある場合のみです。Codexもenv_varsに記載された名前を転送します。クライアントはセッション開始時に設定を読み込むため、編集後は新しいセッションを開始してください。

オープンソース版Opikでリクエストが/opik/apiに送られる — COMET_URL_OVERRIDEはセルフホストのCometプラットフォーム用です。オープンソース版はAPIを/apiで提供します。代わりにOPIK_URL=http://localhost:5173/api（またはhttps://<host>/api）を設定してください。ホストがこのマシンの場合、サーバーは起動時に警告を表示し、--checkは「No Opik API at …」と回答します。

Cursorの呼び出しが60秒でタイムアウトする — これはopik-mcpではなく、Cursorの既知のバグです。呼び出しの範囲を絞る（sizeを小さくする、期間を短くする）か、厳しい上限のないClaude Codeで同じ操作を実行してください。

サーバーが表示されない、サインインが開かない、ワークスペースが違う、uvxが見つからない。 これらについてはドキュメントのトラブルシューティングセクションをご覧ください。 uvx opik@latest mcp statusを実行すると、サーバーが設定されているすべてのクライアントと、設定に差異があるかどうかが表示されます。

開発

git clone [email protected]:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --locked --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 --locked --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 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, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← migration guide for the deprecated v2 TS server (source: tag `legacy-typescript-final`)
├── pyproject.toml
└── Makefile

ヘルプを得る

バグや機能リクエストについては、イシューを作成してください
SDK／バックエンドのドキュメントについては、Opikのドキュメントをご覧ください
質問については、CometコミュニティのSlackをご利用ください

ライセンス

Apache-2.0。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。