Comet Opik

resmi

Kueri dan analisis log Opik, jejak, prompt, dan semua data telemetri lainnya dari LLM Anda dalam bahasa alami.

GitHub

217

Apa yang bisa Anda lakukan dengan Comet Opik MCP?

Jelajahi dan cari ruang kerja Opik Anda — daftarkan proyek, eksperimen, trace, span, prompt, atau rangkaian pengujian dengan filter nama opsional dan paginasi melalui list.
Periksa entitas apa pun berdasarkan ID, nama, atau URI — ambil detail lengkap (termasuk anak sebaris untuk trace dan prompt) menggunakan read dengan URI opik:// atau UUID.
Catat trace, skor, komentar, dan versi prompt — buat atau perbarui trace dan span, lampirkan skor umpan balik, simpan versi prompt, dan kelola rangkaian pengujian melalui write.
Ajukan pertanyaan investigatif kepada Ollie tentang data observabilitas LLM Anda — kueri ask_ollie untuk membandingkan eksperimen, mendiagnosis regresi, atau mensintesis wawasan lintas entitas dengan skor tengah alur opsional.
Jalankan eksperimen evaluasi dari awal hingga akhir — picu run_experiment dengan prompt, rangkaian pengujian, dan pemberi skor untuk mengeksekusi dan mencatat seluruh proses evaluasi.
Introspeksi skema operasi tulis — gunakan schema untuk mengambil bentuk JSON yang tepat dan kolom wajib untuk operasi tulis apa pun sebelum menyusun payload.

Dokumentasi

Opik MCP Server

Server Model Context Protocol (MCP) resmi untuk Opik, platform observabilitas dan evaluasi LLM sumber terbuka, yang dibangun oleh Comet. Hubungkan host AI Anda (Claude Code, Cursor, VS Code Copilot, MCP Inspector) langsung ke ruang kerja Opik Anda: baca trace, catat skor, simpan versi prompt, dan ajukan pertanyaan investigatif kepada Ollie, asisten AI dalam produk Opik, semuanya dari obrolan.

Dibangun untuk insinyur LLM yang sudah menjalankan Opik dan ingin mengendalikannya dari asisten AI yang sama yang mereka gunakan untuk coding.

Migrasi dari npx opik-mcp yang lama? Server TypeScript sudah tidak digunakan lagi dan akan dihentikan pada 2026-11-15. Ganti npx -y opik-mcp dengan uvx opik-mcp@latest di konfigurasi klien MCP Anda. Panduan lengkap: 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

Instalasi

opik-mcp adalah paket Python (membutuhkan Python 3.13+). Cara yang disarankan untuk menjalankannya adalah uvx, yang mengambil dan menjalankan versi terbaru yang dipublikasikan sesuai permintaan — tanpa instalasi global, tanpa repot mengelola virtualenv.

Instal uv sekali saja:

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

Anda memerlukan dua hal dari ruang kerja Opik Anda:

OPIK_API_KEY — dapatkan dari comet.com/api/my/settings/.
OPIK_WORKSPACE — nama ruang kerja Anda (huruf kecil, seperti yang muncul di URL). Misalnya https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Opsional — defaultnya adalah default (konvensi Opik SDK), yang benar untuk instalasi lokal/OSS; pengguna cloud dengan ruang kerja bernama harus mengaturnya. COMET_WORKSPACE diterima sebagai alias yang sudah tidak digunakan lagi.

Catatan pra-rilis: opik-mcp (Python) belum dipublikasikan ke PyPI. Sampai rilis PyPI pertama tersedia, ganti uvx opik-mcp di cuplikan mana pun di bawah ini dengan: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE bersifat opsional. Abaikan baris/kunci OPIK_WORKSPACE di cuplikan mana pun di bawah ini dan server akan menggunakan ruang kerja default (benar untuk instalasi lokal/OSS). Atur hanya jika Anda terhubung ke ruang kerja cloud bernama.

Claude Code

Tambahkan server dengan satu perintah:

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

Atau edit ~/.claude.json secara langsung:

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

Mulai ulang Claude Code. Verifikasi dengan /mcp — opik-mcp akan muncul sebagai terhubung. Kemudian, di obrolan, tanyakan: "list my Opik projects" — Claude akan memanggil alat list dan Anda akan melihat proyek ruang kerja Anda.

Cursor

Edit ~/.cursor/mcp.json (global) atau .cursor/mcp.json (proyek), atau buka 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>"
      }
    }
  }
}

Muat ulang Cursor; titik hijau di sebelah opik-mcp di panel MCP mengonfirmasi koneksi. Tanyakan di obrolan: "list my Opik projects".

Cursor batas waktu 60 detik. Cursor memberlakukan batas waktu panggilan alat yang ketat yang tidak diatur ulang pada notifikasi progres. Giliran ask_ollie yang panjang akan gagal di Cursor. Lihat Batas host yang diketahui.

VS Code Copilot

.vscode/mcp.json di ruang kerja Anda (atau User Settings JSON):

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

Muat ulang jendela; indikator MCP Copilot Chat menunjukkan opik-mcp setelah server dapat dijangkau. Tanyakan di obrolan: "list my Opik projects".

MCP Inspector (pengujian manual)

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

Opik Self-hosted

Tambahkan COMET_URL_OVERRIDE (dan OPIK_URL jika Opik berada di jalur non-default) ke blok env yang sama di konfigurasi host Anda:

{
  "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 dan run_experiment hanya tersedia di Comet Cloud — pada self-hosted panggilan tersebut akan gagal saat pengiriman, jadi gunakan read / list / write secara langsung. Mengatur OPIK_MCP_ANALYTICS_SOURCE="" membuat instalasi Anda tidak menyertakan label sumber cloud-Comet pada peristiwa telemetri.

Alat

opik-mcp menyediakan permukaan kecil yang berorientasi pada hasil — enam alat yang mencakup siklus hidup penuh (baca → anotasi → kurasi → tulis → iterasi).

Alat	Tujuan
`read`	Baca universal berdasarkan id / nama / URI `opik://`
`list`	Daftar universal dengan filter nama opsional + paginasi
`ask_ollie`	Investigasi / sintesis melalui asisten dalam produk Opik
`write`	Tulis universal — catat trace/span, skor, komentar, simpan prompt, kelola rangkaian pengujian & eksperimen
`schema`	Introspeksi skema operasi tulis (digunakan oleh LLM untuk membuat payload yang valid)
`run_experiment`	Jalankan eksperimen evaluasi end-to-end melalui Ollie

`read`

Satu alat untuk pertanyaan "tunjukkan X" apa pun. Menerima entity_type plus id (UUID atau, untuk tipe yang dapat dinamai, sebuah nama) atau URI opik:// lengkap. Pembacaan komposit (trace, prompt) menyertakan turunannya sehingga satu panggilan mengembalikan gambaran lengkap.

Entitas yang didukung: project, trace, span, test_suite, experiment, prompt. Pencarian berbasis nama tersedia untuk project, experiment, prompt, test_suite (lebih lambat — dua panggilan API — dan mungkin mengembalikan beberapa kecocokan).

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

`list`

Jelajahi koleksi dengan filter nama opsional dan paginasi. Tipe dengan cakupan proyek (trace, test_suite_item, prompt_version) memerlukan UUID induknya.

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`

Untuk pertanyaan investigatif, sintesis lintas entitas, atau apa pun yang membutuhkan keahlian domain Opik. Ollie memiliki akses baca langsung ke ruang kerja Anda dan dapat mengeksekusi penulisan (skor, komentar, item rangkaian pengujian, versi prompt) di tengah proses saat diminta.

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.")

Mengembalikan teks akhir asisten plus thread_id. Berikan kembali pada tindak lanjut untuk mempertahankan konteks — Ollie tidak memiliki memori di seluruh thread.

Mode YOLO (default). Penulisan yang dilakukan Ollie di tengah proses dieksekusi tanpa konfirmasi per tindakan. Setiap persetujuan otomatis dicatat sebagai baris audit JSON pada logger Python opik_mcp.audit. Untuk memerlukan konfirmasi, atur OPIK_MCP_AUTO_APPROVE=disabled — permintaan konfirmasi Ollie kemudian muncul sebagai kesalahan bertipe yang dapat Anda terbitkan ulang secara manual.

Hanya tersedia di Comet Cloud.

`write`

Dispatcher tulis universal. Berikan operation + data dan dispatcher memvalidasi payload, menerapkan kata kerja REST yang tepat, dan mengembalikan respons backend.

Operasi:

Operasi	Fungsinya
`trace.create`	Catat satu trace (atau batch). Induk untuk span / skor / komentar.
`trace.update`	Finalisasi atau ubah trace yang ada.
`span.create`	Catat span pada trace yang ada (atau batch).
`score.create`	Lampirkan skor umpan balik numerik ke trace, span, atau thread.
`comment.create`	Lampirkan komentar teks bebas ke trace, span, atau thread.
`prompt_version.save`	Simpan versi prompt baru (membuat prompt berdasarkan nama jika belum ada).
`test_suite.create`	Buat rangkaian pengujian evaluasi.
`test_suite_item.upsert`	Upsert item ke dalam rangkaian pengujian (selalu bentuk envelope).
`experiment.create`	Buat eksperimen dengan cakupan rangkaian pengujian.
`experiment_item.create`	Lampirkan baris trace + dataset_item ke eksperimen.

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

`schema`

Periksa bentuk JSON yang tepat dan bidang yang diperlukan dari setiap operasi tulis sebelum Anda memanggilnya — berguna saat Anda tidak yakin seperti apa seharusnya data. Mengembalikan skema, cakupan OAuth, dan satu contoh yang divalidasi. Pencarian murni, tanpa panggilan backend.

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

`run_experiment`

Jalankan eksperimen evaluasi end-to-end melalui Ollie. Menerima satu dict experiment_config yang mencerminkan bentuk eksperimen Opik (prompt, rangkaian pengujian, penilai); Ollie mengeksekusi proses dan menulis hasilnya kembali sebagai eksperimen Opik.

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

Hanya tersedia di Comet Cloud.

Konfigurasi

Setiap pengaturan adalah variabel lingkungan. Yang wajib dicetak tebal.

Identitas / endpoint

Variabel	Default	Catatan
`OPIK_API_KEY`	—	Wajib untuk `ask_ollie` dan setiap baca/tulis yang diautentikasi.
`OPIK_WORKSPACE`	`default`	Nama ruang kerja. Opsional — fallback ke `default` (konvensi Opik SDK). Pengguna cloud dengan ruang kerja bernama harus mengaturnya.
`COMET_WORKSPACE`	—	Alias usang untuk `OPIK_WORKSPACE` (kompatibilitas mundur). `OPIK_WORKSPACE` menang jika keduanya diatur.
`COMET_WORKSPACE_ID`	—	UUID ruang kerja opsional. Dicap ke dalam peristiwa analitik saat diatur sehingga BI dapat bergabung pada id yang stabil daripada nama ruang kerja (yang dapat berubah).
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Atur ke host Comet self-hosted Anda, atau `https://dev.comet.com` untuk staging.
`OPIK_URL`	diturunkan dari `COMET_URL_OVERRIDE` + `/opik/api`	Timpa hanya jika Opik berada di host/jalur yang berbeda dari UI Comet.
`OPIK_DEFAULT_PROJECT_NAME`	tidak diatur	Saat diatur, blob `instructions` per sesi memberi tahu LLM untuk meneruskan ini sebagai `project_name` pada setiap panggilan alat kecuali pengguna menyebutkan proyek yang berbeda.

Server / transport

Variabel	Default	Catatan
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` untuk diluncurkan host, `streamable-http` untuk mendengarkan pada port.
`OPIK_MCP_HOST`	`127.0.0.1`	host bind uvicorn (hanya `streamable-http`).
`OPIK_MCP_PORT`	`8080`	port bind uvicorn (hanya `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	`true` untuk mengaktifkan `--reload` uvicorn (hanya dev).
`OPIK_MCP_AS_URL`	tidak diatur	URL Server Otorisasi OAuth, diiklankan di `/.well-known/oauth-protected-resource` (RFC 9728) dan digunakan sebagai target proxy untuk probe penemuan AS. Diperlukan agar host MCP dapat memulai proses OAuth melalui HTTP.
`OPIK_MCP_RESOURCE_URI`	tidak diatur	URI publik kanonis server ini, diiklankan sebagai `resource` di metadata sumber daya yang dilindungi dan digunakan untuk menurunkan petunjuk `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	ambang batas logger stderr.

Memilih transport

opik-mcp melakukan tidak ada validasi kredensial lokal pada transport HTTP: setiap Authorization: Bearer … yang terbentuk dengan baik (kunci API Opik atau token akses OAuth opik_mcp_at_…) diteruskan verbatim ke backend-opik, yang merupakan satu-satunya titik penegakan otentikasi. Pilih transport berdasarkan bentuk deployment:

Skenario	Transport
Klien MCP dan Opik di mesin yang sama (instalasi OSS lokal)	stdio (disarankan — paling sederhana, tanpa port, tanpa pengaturan OAuth)
Klien MCP lokal → Opik jarak jauh (Comet cloud / self-hosted)	stdio dengan `OPIK_API_KEY`, atau HTTP dengan OAuth (`OPIK_MCP_AS_URL` menunjuk ke backend)
opik-mcp yang dihosting di belakang edge yang sama dengan backend-opik	HTTP — bearer divalidasi oleh backend per permintaan

Catatan untuk instalasi OSS lokal: backend OSS tidak mengautentikasi permintaan, jadi opik-mcp HTTP di depannya seterbuka REST API OSS itu sendiri. Pertahankan bind 127.0.0.1 default (dan lebih suka stdio) di jaringan bersama.

Ollie / panggilan panjang

Variabel	Default	Catatan
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` untuk memerlukan persetujuan per tindakan sebelum penulisan tengah proses Ollie berlanjut. Pada host yang mengiklankan kemampuan MCP `elicitation`, pengguna melihat prompt ya/tidak; pada host yang lebih sederhana, permintaan muncul sebagai kesalahan bertipe yang dapat Anda terbitkan ulang secara manual.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Berapa lama prompt konfirmasi tengah proses Ollie dapat menunggu pengguna sebelum dianggap sebagai pembatalan. `0` menonaktifkan batas (hanya debug).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Batas polling cold-start pod Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Interval polling cold-start.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Irama watchdog — memancarkan tick `notifications/progress` saat pod diam, menjaga batas waktu host tetap terkendali.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Batas keras pada keheningan pod sebelum `ask_ollie` dibatalkan. `0` menonaktifkan (hanya debug).

Telemetri

Event penggunaan anonim (hanya jenis event + waktu — tanpa konten kueri). Digest SHA-256 dari kunci API Anda disertakan agar dukungan dapat menemukan akun Anda; kunci mentah tidak pernah meninggalkan proses. Cara menolak: OPIK_MCP_ANALYTICS_ENABLED=false.

Variabel	Default	Catatan
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Atur ke `false` untuk menonaktifkan semua telemetri.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Penggantian untuk staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Tag pada setiap event (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Penerima menggunakan ini untuk menandai `on_prem=False`. Instalasi on-prem harus mengganti ke `""` atau domain mereka sendiri.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Timeout koneksi HTTP.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Timeout total permintaan HTTP.

Batasan host yang diketahui

Spesifikasi MCP memungkinkan host mereset timeout panggilan alat mereka pada notifications/progress — opik-mcp mengirimkan satu per event SSE Ollie ditambah heartbeat watchdog 15 detik. Kenyataannya tidak merata:

Claude Code — tidak ada timeout panggilan alat yang terdokumentasi; heartbeat menjaga panggilan tetap hidup hingga message_end. Direkomendasikan.
Cursor — timeout keras 60 detik yang tidak mereset saat ada progres (bug upstream). Giliran Ollie yang panjang akan gagal. Jaga kueri ask_ollie tetap fokus.
MCP Inspector — MAX_TOTAL_TIMEOUT membatasi durasi total (default 60 detik). Naikkan di UI Inspector untuk operasi yang panjang.

Jika panggilan macet, atur OPIK_MCP_LOG_LEVEL=DEBUG — kegagalan heartbeat (biasanya host terputus) dicatat di opik_mcp.ask_ollie pada level debug.

Pemecahan masalah

OPIK_API_KEY is required to use ask_ollie — variabel tidak mencapai proses server. Di Claude Code / Cursor / VS Code, variabel env hanya berlaku saat berada di dalam blok env dari konfigurasi server MCP, bukan shell Anda. Mulai ulang host setelah mengedit.

ask_ollie mengembalikan "pod not ready" setelah 2 menit — cold-start pod Ollie melebihi OPIK_MCP_POD_READY_TIMEOUT_S. Coba lagi — panggilan kedua biasanya mengenai pod yang hangat.

ask_ollie / run_experiment gagal dengan error dispatch di Opik self-hosted — alat tersebut hanya tersedia di Comet Cloud. Gunakan read / list / write langsung di self-hosted.

Panggilan Cursor timeout pada 60 detik — bug yang diketahui di Cursor, bukan opik-mcp. Persingkat kueri Ollie, atau jalankan operasi yang sama di Claude Code yang tidak memiliki batas keras.

Pengembangan

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

Target umum:

Target	Fungsinya
`make install`	`uv sync --extra dev`
`make run`	Jalankan server MCP (stdio secara default).
`make run-dev`	Jalankan dengan pencatatan DEBUG + uvicorn `--reload`.
`make dev`	Jalankan melalui `mcp dev` (pembungkus mode-dev Inspector).
`make inspect`	Luncurkan MCP Inspector terhadap server yang berjalan.
`make test`	`uv run pytest -q`.
`make test-live`	End-to-end langsung terhadap `dev.comet.com` (atur `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + pemeriksaan format.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Tata letak repo:

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

Dapatkan bantuan

Buka isu untuk bug dan permintaan fitur
Dokumentasi Opik untuk dokumentasi SDK / backend
Slack komunitas Comet untuk pertanyaan

Meningkatkan dari v2? Server TypeScript lawas masih dikirimkan di npm sebagai opik-mcp@^2 (npx -y opik-mcp); sumbernya dipertahankan di bawah legacy/typescript/. Lihat legacy/typescript/DEPRECATED.md untuk kebijakan dukungan.

Lisensi

Apache-2.0.