Comet Opik

Server MCP Opik

Server Model Context Protocol (MCP) resmi untuk Opik, platform observabilitas dan evaluasi LLM sumber terbuka yang dibuat oleh Comet. Hubungkan host AI Anda (Claude Code, Cursor, VS Code Copilot, Codex, opencode, atau klien MCP apa pun) langsung ke ruang kerja Opik Anda: baca trace, catat skor, dan simpan versi prompt, semuanya dari chat.

Dibuat untuk engineer LLM yang sudah menggunakan Opik dan ingin mengoperasikannya dari asisten AI yang sama dengan yang mereka gunakan untuk menulis kode.

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

---

Mulai cepat

Satu perintah menyiapkan Opik di klien AI pada mesin Anda, termasuk Claude Code. Perintah ini menemukan Opik Anda (yang tersimpan di ~/.opik.config, yang berjalan di localhost, atau menanyakan pilihan Anda), mendaftarkan server MCP, memasang paket skill Opik, dan memeriksa koneksi. Di Opik Cloud, Anda tidak perlu mengurus kunci API: klien Anda masuk melalui browser. Perintah ini memerlukan uv dan tidak memerlukan Opik SDK:

uvx opik@latest mcp configure

Tanpa terminal, misalnya dari agen coding atau skrip, sebutkan nama klien:

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

--ai-client juga menerima codex, cursor, vscode dan opencode. Jika dijalankan dengan cara itu, perintah ini menggunakan Opik yang tersimpan di ~/.opik.config, termasuk kunci API, atau Opik yang merespons di localhost. Jika tidak menemukan keduanya, perintah akan berhenti dan meminta --deployment.

Agen coding yang diminta untuk "install opik mcp" mendapatkan langkah-langkah lengkap, termasuk hal yang perlu ditanyakan kepada pengguna, dari uvx opik-mcp@latest --help. Langkah-langkahnya sama dengan Instal dengan agen coding di bawah.

Mendaftarkan server secara manual, menggunakan perintah klien di bagian Siapkan secara manual, melewati pemeriksaan Opik yang Anda gunakan dan pemasangan paket skill. Karena itu, cara ini ditujukan untuk klien yang tidak didukung oleh installer.

Opik Anda	Server	Transport	Login
Opik Cloud (www.comet.com)	server yang di-host, dijalankan oleh Comet	Streamable HTTP	melalui browser (OAuth); tanpa kunci API
Comet yang di-host sendiri, Opik sumber terbuka	server lokal, paket ini	stdio	variabel env; kunci API hanya jika diperlukan oleh deployment

Klien memuat server MCP saat sesi dimulai, jadi mulailah sesi baru setelahnya.

Panduan penyiapan, pemecahan masalah, dan FAQ: comet.com/docs/opik/mcp-server.

---

Opik Cloud: server yang di-host

Comet menjalankan server di https://www.comet.com/opik/api/v1/mcp. Klien Anda terhubung melalui HTTP dan membuka browser untuk login pertama kali. Tidak ada yang perlu dipasang, tidak ada kunci API, dan tidak perlu mengatur ruang kerja: server bekerja di ruang kerja yang Anda pilih saat login. Setelah menambahkannya, mulai sesi baru dan tanyakan: "list my Opik projects".

Perintah Mulai cepat menyiapkannya untuk Claude Code, Codex, Cursor, VS Code Copilot, dan opencode, beserta paket skill. Di Claude Code, plugin melakukan hal yang sama dengan satu perintah. Tombol di bawah menambahkannya ke Cursor atau VS Code dengan sekali klik; cara lain untuk mendaftarkannya secara manual tersedia di bagian Siapkan secara manual.

Plugin Claude Code

Plugin opik memasang skill Opik dan mendaftarkan server MCP yang di-host untuk Opik Cloud:

/plugin install opik --marketplace comet-ml/opik-mcp

Di Claude Code versi sebelum 2.1.275, jalankan /plugin marketplace add comet-ml/opik-mcp, lalu /plugin install opik@opik. Skill dimuat sebagai opik:<skill>, seperti opik:opik-instrument, dan /mcp menampilkan server sebagai plugin:opik:opik-cloud. Server tersebut milik Opik Cloud. Mulai sesi baru, lalu masuk melalui /mcp → Authenticate. Untuk Comet yang di-host sendiri dan menjalankan server OAuth MCP, tambahkan dengan claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; untuk Opik lain yang di-host sendiri atau bersumber terbuka, gunakan perintah Mulai cepat. Lalu nonaktifkan plugin:opik:opik-cloud di /mcp. Claude Code tidak memperbarui plugin dari marketplace ini secara otomatis: jalankan /plugin marketplace update opik, lalu /plugin update opik@opik, atau aktifkan pembaruan otomatis untuk marketplace di /plugin. Marketplace ini menyediakan main, yang mungkin lebih baru daripada rilis terakhir. Pembaruan hanya tersedia saat versi plugin berubah, pada setiap rilis.

Jika sebelumnya Anda menambahkan opik-mcp di URL yang sama, Claude Code akan mempertahankan salinan Anda dan melewati salinan dari plugin. Jika milik Anda adalah server lain, seperti uvx opik-mcp lokal, keduanya akan dimuat: jalankan claude mcp remove opik-mcp agar hanya salinan dari plugin yang tersisa. Skill dari paket skill juga dimuat bersama salinan dari plugin; hapus dengan npx skills remove --global --agent claude-code, yang akan menanyakan skill mana yang ingin dihapus.

---

Opik yang di-host sendiri dan bersumber terbuka: server lokal

opik-mcp berjalan di mesin Anda: klien memulainya dengan uvx opik-mcp dan berkomunikasi dengannya melalui stdio. Perintah Mulai cepat menyiapkannya dari ~/.opik.config atau Opik lokal Anda; untuk mendaftarkannya secara manual, lihat Siapkan secara manual. Pasang uv sekali; saat pertama kali digunakan, alat ini mengambil paket dan Python 3.13 jika diperlukan:

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

uvx opik-mcp menggunakan kembali salinan yang telah di-cache oleh uv, sehingga prosesnya dimulai dengan cepat; uv cache clean opik-mcp membuat proses berikutnya mengambil rilis terbaru. uvx opik-mcp@latest memeriksa PyPI setiap kali dimulai, yang menambah waktu sekitar satu setengah detik. Codex menunggu selama mcp_optional_startup_grace_ms (1 s secara default) untuk server sebelum membuat daftar alat pertama, sehingga proses mulai yang lebih lambat dapat membuat alat tidak tersedia pada giliran pertama. Perintah sekali jalan dalam README ini (opik mcp configure, opik mcp status, --help, --check) menyertakan @latest, sehingga tidak akan pernah menjalankan salinan yang di-cache uv berbulan-bulan lalu.

Variabel env mengarahkan server ke Opik Anda:

Opik Anda	Variabel env
Opik sumber terbuka di mesin ini	OPIK_URL=http://localhost:5173/api
Opik sumber terbuka di server	OPIK_URL=https://<host>/api, ditambah OPIK_API_KEY hanya jika deployment menambahkan autentikasi
Platform Comet yang di-host sendiri (UI Opik berada di https://<host>/opik)	COMET_URL_OVERRIDE=https://<host>, OPIK_WORKSPACE, OPIK_API_KEY

• Opik sumber terbuka menyediakan API di /api dan hanya memiliki satu ruang kerja, default, jadi tidak memerlukan OPIK_WORKSPACE. COMET_URL_OVERRIDE akan mengarahkan server ke /opik/api, yang tidak disediakan oleh Opik sumber terbuka.
• Comet yang di-host sendiri memiliki ruang kerja bernama. Atur OPIK_WORKSPACE ke segmen setelah /opik/ di URL Opik Anda; jika tidak diatur, data yang dibaca berasal dari ruang kerja default akun Anda, tanpa pesan kesalahan yang menjelaskannya.
• Comet yang di-host sendiri dan menjalankan server OAuth MCP (dinonaktifkan secara default) dapat menggunakan alur hosted, di https://<host>/opik/api/v1/mcp.
• Ganti setiap nilai. Server menolak ruang kerja placeholder seperti <your-workspace> atau ${input:OPIK_WORKSPACE}; URL placeholder akan dikirim apa adanya dan gagal terhubung.
• OPIK_MCP_ANALYTICS_SOURCE="" di blok env membuat instalasi yang di-host sendiri tidak menyertakan label sumber cloud-Comet pada peristiwa telemetri.

Sebelum menambahkan server ke klien, periksa pengaturannya: jalankan server dengan env dan --check yang sama. Server melakukan satu panggilan ke Opik dan mencetak ruang kerja serta jumlah proyek yang ditemukan, atau hal yang perlu diperbaiki beserta tautan ke dokumentasi, lalu keluar dengan kode 0 atau 1. Klien tidak dapat memberi tahu Anda hal ini sebelum sesi baru dimulai: Claude Code menampilkan Connected meskipun kuncinya salah, dan Codex tidak memulai apa pun sampai saat itu.

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

Lalu daftarkan server di klien Anda: server lokal, secara manual.

---

Instal dengan agen coding

Untuk agen AI yang diminta memasang server, misalnya dengan perintah "install opik mcp". Tujuannya adalah mendaftarkan server untuk Opik pengguna, memasang paket skill Opik, dan memastikan pengguna sudah masuk. Cari tahu Opik mana yang digunakan dari mesin ini, dan tanyakan kepada pengguna hanya hal yang tidak dapat Anda ketahui: satu pertanyaan per pesan, dan tunggu setiap jawaban sebelum mengajukan pertanyaan berikutnya. Installer pada langkah 3 melakukan seluruh penyiapan dalam satu kali jalan, jadi selesaikan langkah 1 dan 2 sebelum menjalankannya. uvx opik-mcp@latest --help menampilkan langkah-langkah ini.

1. Periksa yang sudah tersedia.

   uvx opik@latest mcp status
   

   Perintah ini menampilkan Opik yang tersimpan di ~/.opik.config (URL dan ruang kerja, tidak pernah kuncinya) serta klien yang sudah memiliki server. Di Claude Code, jalankan juga claude mcp list: perintah ini menampilkan konektor claude.ai dan entri dengan nama lain. Perintah ini juga mencetak perintah untuk setiap entri, yang pada entri npx lama dapat berisi kunci API: jangan ulangi perintah tersebut.

   • Server untuk https://www.comet.com/opik/api/v1/mcp dengan nama apa pun, seperti konektor claude.ai, berarti server sudah terdaftar: jangan tambahkan server kedua. Pasang paket skill saja dengan npx skills add comet-ml/opik-skills -g --all. Lanjutkan ke langkah 4 jika server menampilkan ! Needs authentication.
   • Installer mengganti entri opik-mcp yang sudah ada tanpa bertanya, misalnya entri untuk server npx lama. Tanyakan kepada pengguna sebelum menjalankannya.

2. Cari tahu Opik yang digunakan pengguna.

   • Tersimpan di ~/.opik.config: gunakan itu, dan beri tahu pengguna Opik mana yang sedang Anda siapkan. Installer membacanya, termasuk kunci API, jadi jangan meminta kunci.
   • Tidak ada ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. Jawaban berarti Opik sumber terbuka ada di mesin ini. Di shell yang di-sandbox, seperti milik Codex, tidak ada jawaban bisa berarti shell tidak memiliki jaringan, bukan berarti Opik tidak tersedia.
   • Tidak keduanya: tanyakan kepada pengguna, dan jangan memilih sendiri. URL Opik di proyek, seperti OPIK_URL_OVERRIDE di .env, memungkinkan Anda mengajukan pertanyaan ya atau tidak. Jika tidak: "Opik mana yang Anda gunakan: Opik Cloud (www.comet.com), Opik sumber terbuka (URL-nya), atau platform Comet yang di-host sendiri (URL dan ruang kerjanya)?"

3. Jalankan installer untuk klien yang Anda gunakan. Installer memasang paket skill Opik bersama server, dengan atau tanpa --skills; pertahankan flag tersebut dalam perintah yang Anda berikan kepada pengguna untuk dijalankan nanti. Di Opik Cloud, installer membuka browser untuk login dan menunggu selama satu menit, jadi beri tahu pengguna terlebih dahulu.

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

   --ai-client juga menerima codex, cursor, vscode dan opencode. Untuk Opik yang tersimpan di ~/.opik.config atau berjalan di localhost, jalankan apa adanya: --deployment menyisihkan konfigurasi tersimpan, termasuk kunci API. Jika keduanya tidak ada, tambahkan flag untuk Opik yang disebutkan pengguna pada langkah 2:

   Opik pengguna	Tambahkan
   Opik Cloud, www.comet.com	--deployment cloud
   Opik sumber terbuka	--deployment local, dan --url <url> jika tidak berjalan di localhost
   Platform Comet yang di-host sendiri, /opik/ di URL-nya	--deployment self-hosted --url <url> --workspace <workspace>, dengan OPIK_API_KEY di shell

   Jika gagal, misalnya karena Opik tidak merespons, beri tahu pengguna apa yang dicetak dan apa yang perlu diperiksa, seperti VPN atau URL. Jangan beralih ke Opik lain.

4. Login untuk Opik Cloud. Jika installer melaporkan bahwa server belum masuk, minta pengguna menjalankan claude mcp login opik-mcp, atau /mcp dalam sesi Claude Code, alih-alih menjalankannya sendiri: perintah tersebut menunggu browser. Konektor claude.ai melakukan login melalui /mcp. Proses login meminta ruang kerja; sebutkan ruang kerja yang tersimpan di ~/.opik.config, jika ada.

5. Selesaikan. Beri tahu pengguna apa yang dipasang dan apa yang masih perlu dilakukan. Sebutkan paket skill: skill Opik, yang dipasang untuk setiap proyek dan mengajarkan agen cara menginstrumentasi, mengevaluasi, serta men-debug dengan Opik. Klien memuat server MCP dan skill saat sesi dimulai: minta pengguna memulai sesi baru, lalu mencoba "list my Opik projects".

Untuk semua cara:

• Jangan meminta pengguna menempelkan kunci API ke chat. Server hosted tidak memerlukannya; jika tidak, ambil dari lingkungan shell ("$OPIK_API_KEY"), atau minta pengguna menjalankan perintahnya.

• Jangan menebak ruang kerja. Ruang kerja adalah segmen setelah comet.com/opik/ (atau /opik/ pada Comet yang di-host sendiri) di URL Opik pengguna.

• Jangan mencetak ~/.claude.json atau ~/.opik.config: keduanya dapat berisi kunci API. uvx opik@latest mcp status dan claude mcp list menampilkan hal yang Anda perlukan, dan installer membaca konfigurasi itu sendiri.

• Jika pemeriksaan izin memblokir perintah, jangan mencari cara untuk mengakalinya. Berikan perintah yang perlu dijalankan pengguna (di Claude Code, ! sebelum menjalankannya dari prompt). Untuk klien yang tidak dikenali oleh penginstal, daftarkan secara manual dengan perintah di Siapkan secara manual: server ter-host untuk Opik Cloud, dan server lokal untuk yang lainnya.

• Sebelum mendaftarkan server lokal, jalankan dengan env yang akan Anda teruskan dan --check, dengan OPIK_API_KEY diekspor di shell, bukan ditulis pada perintah: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Perintah ini keluar dengan kode 0 dan menyebutkan workspace yang terdeteksi, atau mencetak hal yang perlu diperbaiki. Setelah terdaftar, Claude Code melaporkan Connected meskipun kuncinya salah, dan Codex tidak memiliki pemeriksaan.

• Claude Code menolak menambahkan entri opik-mcp yang sudah ada, jadi hapus terlebih dahulu dengan claude mcp remove opik-mcp --scope user; perintah add milik Codex akan menggantikannya.

• Setelah mendaftar, di Claude Code, baca baris status saja: claude mcp get opik-mcp | grep Status. Keluaran lengkap mencetak blok env, termasuk kunci API. Server ter-host menampilkan ! Needs authentication sampai claude mcp login opik-mcp dijalankan. Codex tidak memiliki apa pun yang memulai server sebelum sesi; codex mcp get opik-mcp menampilkan yang tersimpan, dengan nilai env disamarkan.

---

Siapkan secara manual (tanpa pemeriksaan Opik, tanpa paket skill)

Perintah Mulai cepat melakukan semua ini untuk Claude Code, Codex, Cursor, VS Code Copilot, dan opencode, serta memeriksa Opik yang Anda gunakan dan memasang paket skill. Daftarkan secara manual hanya untuk klien lain, atau untuk melihat apa yang ditulis penginstal. Agen coding yang memasang untuk pengguna menjalankan penginstal: lihat Pasang dengan agen coding.

Server ter-host (Opik Cloud)

Claude Code, secara manual

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

Lalu masuk dari /mcp → Authenticate dalam sesi Claude Code. Browser akan terbuka, jadi orang yang berada di depan keyboard yang melakukannya; dari terminal mereka sendiri, claude mcp login opik-mcp melakukan hal yang sama. --scope user membuat server tersedia di setiap proyek; tanpa opsi ini, Claude Code hanya mendaftarkannya untuk direktori saat ini. Melalui SSH, claude mcp login opik-mcp --no-browser mencetak URL masuk untuk dibuka di mesin Anda sendiri; langkah terakhir memerlukan terminal interaktif (ssh -t).

Codex, secara manual

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

add membuka proses masuk; codex mcp login opik-mcp membukanya lagi. Di ~/.codex/config.toml, server yang sama adalah:

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

Cursor, secara manual

Gunakan tombol di bawah server ter-host, atau tambahkan ke ~/.cursor/mcp.json:

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

VS Code Copilot, secara manual

Gunakan tombol di bawah server ter-host, atau tambahkan ke .vscode/mcp.json di workspace Anda atau ke mcp.json pengguna Anda (MCP: Open User Configuration):

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

Klien lain

Klien apa pun yang menerima URL dapat menggunakan server ter-host:

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

Klien yang hanya dapat menjalankan perintah lokal dapat mengaksesnya melalui npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp.

Opik Cloud dengan kunci API

Jika tidak ada yang dapat menyelesaikan proses masuk browser, misalnya saat agen berjalan tanpa pengawasan dari skrip atau klien tidak mendukung MCP OAuth, gunakan kunci API dari comet.com/api/my/settings/ sebagai gantinya, dengan server lokal yang diarahkan ke Opik Cloud:

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

Klien lain menggunakan dua variabel yang sama dalam blok env mereka. Atur OPIK_WORKSPACE ke segmen setelah comet.com/opik/ di URL Opik Anda (https://www.comet.com/opik/acme-ai/projects → acme-ai). Jika tidak diisi, server mengirimkan default, yang oleh Comet diarahkan ke workspace default akun Anda, sehingga pembacaan dapat berasal dari workspace yang salah tanpa menimbulkan kesalahan.

Server lokal (Opik yang di-host sendiri dan sumber terbuka)

Contoh-contoh ini menggunakan Opik sumber terbuka lokal. Untuk Comet yang di-host sendiri, ganti dengan tiga variabel dari tabel. Setelah menambahkan server, mulai sesi baru dan tanyakan: "list my Opik projects".

Claude Code, secara manual

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

Untuk Comet yang di-host sendiri, dengan kunci di OPIK_API_KEY shell Anda:

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

Atau edit ~/.claude.json secara langsung:

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

claude mcp get opik-mcp menampilkan ✔ Connected setelah server dimulai. Hal itu tidak membuktikan bahwa URL atau kuncinya benar, karena hanya pemanggilan alat yang mencapai Opik; --check (server lokal) yang melakukannya. Perintah ini juga mencetak blok env, termasuk kunci API.

Codex, secara manual

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

Atau edit ~/.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 hanya memberikan variabel dalam env dan nama dalam env_vars kepada server lokal, jadi kunci yang diekspor di shell Anda tidak akan diteruskan jika tidak diatur di sana.

Cursor, secara manual

Tambahkan ke ~/.cursor/mcp.json (global) atau .cursor/mcp.json (proyek), atau gunakan Cmd+Shift+J → Features → Model Context Protocol:

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

Batas waktu Cursor 60 detik. Cursor menerapkan batas waktu pemanggilan alat yang ketat dan tidak diatur ulang oleh notifikasi progres. Lihat Batasan host yang diketahui.

VS Code Copilot, secara manual

Tambahkan ke .vscode/mcp.json di workspace Anda, atau ke mcp.json pengguna Anda (MCP: Open User Configuration):

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

MCP Inspector (pengujian manual)

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

---

Beralih dari npx opik-mcp?

Server TypeScript (npm opik-mcp@2) sudah tidak digunakan lagi dan berhenti melayani permintaan pada 2026-11-15. Untuk instalasi baru, jalankan perintah Mulai cepat; uvx opik-mcp adalah perintah yang dijalankan klien untuk memulai server, bukan penginstal. Untuk memindahkan konfigurasi yang sudah ada di Opik Cloud, beralihlah ke server ter-host dan hapus kunci API. Jika tidak, di konfigurasi klien MCP Anda, ganti npx -y opik-mcp dengan uvx opik-mcp. Beberapa variabel env diganti namanya dan flag baris perintah tidak lagi dibaca: lihat panduan migrasi. Kebijakan dukungan: DEPRECATED.md. Sumber TypeScript tersedia di tag git legacy-typescript-final.

---

Alat

opik-mcp menyediakan serangkaian alat kecil yang berorientasi pada hasil dan mencakup seluruh siklus hidup (baca → beri anotasi → kurasi → buat → iterasi).

Alat	Tujuan
read	Pembacaan universal berdasarkan id / nama / URI opik://
list	Daftar universal dengan filter nama opsional + paginasi
write	Penulisan universal — catat trace/span, beri skor, komentar, simpan prompt, kelola dataset & eksperimen
schema	Introspeksi skema operasi penulisan (digunakan LLM untuk menyusun payload yang valid)
read_skill	Baca salah satu skill agen Opik yang disertakan bersama server ini

read

Satu alat untuk pertanyaan apa pun seperti "tampilkan X". Menerima entity_type beserta id (UUID atau, untuk jenis yang dapat diberi nama, nama) atau URI opik:// lengkap. Pembacaan komposit (trace, prompt, thread, agent_insights_issue) menyertakan turunannya secara langsung sehingga satu pemanggilan memberikan gambaran lengkap.

Seluruh record yang Anda sebutkan akan dikembalikan. Namun, turunan yang disertakan tidak dikembalikan secara utuh: isinya diambil dengan truncate=true milik backend, sehingga field yang lebih dari ~10 KB dipotong di ClickHouse dan gambar base64 diganti dengan "[image]" — jika satu lampiran yang sama diulang di 200 span, biayanya akan lebih besar daripada semua hal lain dalam pembacaan. Jawaban menyebutkan hal ini di spanBodies / messageBodies, dan setiap turunan dapat diambil secara utuh melalui read("span", id) atau read("trace", trace_id) miliknya sendiri, yang mengakses endpoint tanpa parameter truncate sama sekali.

Koleksi yang disertakan juga dibatasi panjangnya: 200 span, 200 giliran, 100 versi prompt. Jika melebihi batas tersebut, spansTruncated / messagesTruncated / versionsTruncated bernilai true dan baris moreSpans / moreMessages / moreVersions di sebelahnya mencantumkan jumlah serta pemanggilan list(...) yang tepat untuk melanjutkan dari bagian yang disertakan.

Entitas yang didukung: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. Pencarian berdasarkan nama tersedia untuk project, experiment, prompt, dataset (lebih lambat — dua panggilan API — dan dapat mengembalikan beberapa hasil). thread dan agent_insights_issue cakupannya terbatas pada proyek: teruskan project_id atau project_name, atau tautan/URI yang memuat proyek tersebut. dataset dan dataset_item sebelumnya disebut test_suite dan test_suite_item; nama lama masih dapat digunakan, tetapi tidak ditampilkan sebagai opsi dan kode baru sebaiknya menggunakan nama baru.

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

Tautan yang disalin dari UI Opik dapat digunakan sebagai id: tautan thread atau tautan halaman Diagnostics memuat proyek, sehingga project_id tidak diperlukan dan jenis entitas diambil dari tautan.

Pembacaan project menjawab "bagaimana kondisi proyek saya" dalam satu pemanggilan. Hasilnya mencakup {project, summary, vocabulary, contains, url}: record, lalu empat angka yang ditampilkan sebagai kartu di halaman Logs (jumlah trace, tingkat kesalahan, durasi rata-rata, total biaya) untuk 7 hari terakhir dibandingkan dengan 7 hari sebelumnya, hanya lalu lintas SDK, seperti yang ditampilkan di layar. since / until menggeser rentang waktu tersebut; since="30d" adalah rentang yang dibuka UI. Tingkat atau rata-rata untuk periode tanpa trace akan dikembalikan sebagai null, karena tingkat kesalahan 0% pada minggu tanpa lalu lintas akan tampak seperti minggu yang sehat.

vocabulary adalah peta yang Anda perlukan sebelum dapat menanyakan hal lain: nama skor umpan balik proyek, kunci penggunaan token, dan aturan otomatisasi yang memberi skor pada trace-nya. Inilah nama-nama yang digunakan dalam filter atau series= di bawah, dan menebaknya akan menghasilkan halaman kosong yang tampak seperti kabar baik. Nama skor dan aturan dibatasi jumlahnya, tetapi jumlah sebenarnya selalu dilaporkan dan pemanggilan untuk mengambil sisanya disebutkan; kunci penggunaan dicantumkan lengkap karena tidak ada cara lain untuk mencantumkannya. contains menyebutkan eksperimen, dataset, versi prompt, dan proses optimisasi terbaru, sehingga pertanyaan "apa yang terjadi di sini" tidak memerlukan empat pemanggilan tambahan. Bagian yang gagal dimuat akan menyatakan kegagalannya, bukan tampak kosong, dan bagian yang kosong tidak disertakan.

Pembacaan agent_insights_issue mengembalikan {issue, example_trace_ids, details}: record masalah Diagnostics (nama, deskripsi, penyebab, saran perbaikan, tingkat keparahan, status), id trace unik yang menunjukkan masalah tersebut (sampel yang sama dengan yang ditampilkan halaman Diagnostics — buka salah satunya dengan read("trace", id)), serta perincian per hari. Isi trace tidak disertakan, sehingga pembacaan tetap hanya memerlukan satu panggilan backend. since / until mempersempit baris per hari; default-nya adalah seluruh waktu. Jika server mengetahui URL Opik dan workspace sesi, pembacaan juga menyertakan url (halaman Diagnostics untuk masalah tersebut) dan trace_url_template (tautan langsung ke trace contoh mana pun), sehingga asisten dapat memberikan tautan yang bisa diklik; dalam sesi OAuth yang workspace-nya tidak dapat ditentukan, tautan tidak disertakan alih-alih ditebak.

Trace sendiri tidak memiliki URL — tautannya tidak dapat diturunkan dari field yang dikembalikan oleh read atau list, dan bentuk URL yang ditebak akan menghasilkan 404. Instruksi sesi menyebutkan templat untuknya, .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., sehingga asisten mengisi id dan memberikan tautan. Tautan ini melewati pengalihan opik-backend, yang menentukan proyek dan workspace dari trace, sehingga tetap berfungsi saat URL proyek langsung tidak bisa digunakan, termasuk dalam sesi OAuth dengan workspace yang belum diketahui. Tautan ini sama dengan yang dicetak Python SDK untuk sebuah trace.

list

Jelajahi atau cari koleksi dengan paginasi. Jenis yang cakupannya terbatas pada proyek (trace, span, thread, agent_insights_issue, dataset_item, prompt_version) memerlukan induknya: UUID atau nama proyek, UUID dataset, atau UUID prompt.

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

Filter. trace, span, thread, experiment dan dataset_item menerima string OQL, dengan tata bahasa yang sama seperti search_traces(filter_string=…) milik SDK:

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

String menggunakan tanda kutip ganda, angka ditulis tanpa tanda kutip, duration dalam milidetik, tanggal berupa instan ISO-8601 dengan zona waktu ("2026-09-08T10:00:00Z"). Skor dan kamus menggunakan kunci: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND adalah satu-satunya konektor.

Seperti halaman Logs di UI, daftar trace, span, dan thread menambahkan source = "sdk" agar trace evaluator, playground, dan eksperimen tidak mengganggu; beri nama source sendiri untuk melihatnya. Baris output pertama menggemakan filter yang diterapkan.

Filter yang tidak valid gagal sebelum mencapai backend, disertai informasi yang diperlukan untuk memperbaikinya: posisi kesalahan sintaks, nama field terdekat, operator yang valid untuk tipe field tersebut, atau format nilai yang diharapkan. Field dengan kumpulan nilai tertutup (source, span type, thread status, visibility_mode) juga diperiksa terhadap kumpulan tersebut, termasuk setiap elemen dalam daftar in. source adalah satu-satunya yang divalidasi sendiri oleh backend, dan backend menjawab nilai yang tidak dikenal dengan 500, bukan 400, sehingga source = "SDK" jika tidak, akan menghasilkan kesalahan server yang tidak jelas untuk huruf kapital. Sisanya dibandingkan sebagai string dan menghasilkan halaman kosong, yang terbaca sebagai "tidak ada kecocokan" padahal artinya "nilai seperti itu tidak ada". Minta schema("list.trace") (atau list.span, list.thread, list.experiment) untuk referensi field lengkap, termasuk nilai yang diterima.

Menemukan satu kasus dalam dataset. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> untuk kunci yang digunakan saat dataset dibuat, full_data untuk substring dari seluruh payload (pemindaian penuh — sebutkan kunci jika bisa), ditambah id, tags, source, trace_id, span_id dan stempel waktu. data.<key> hanya menerima enam operator string (=, !=, contains, not_contains, starts_with, ends_with); backend menjawab perbandingan dengan 400, jadi filter ini ditolak sebelum pemanggilan. Endpoint ini tidak mendukung pengurutan maupun pencarian teks bebas — sort ditolak alih-alih diabaikan. read(entity_type="dataset_item", id=…) mengembalikan satu kasus secara utuh, sehingga nilai yang terpotong di tabel dapat dibaca kembali.

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

Dengan experiment_ids, daftar yang sama menjadi perbandingan — kasus-kasus dengan setiap run terlampir — dan filternya diterapkan pada run (feedback_scores.<name>, output, duration). Keduanya memiliki kumpulan field berbeda pada dua endpoint backend: schema("list.dataset_item_case") adalah kasus milik dataset, schema("list.dataset_item") adalah perbandingannya.

Pengurutan. trace, span, thread dan experiment menerima sort="<field> [asc|desc]", dengan nilai default desc, dan hanya satu field: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". Field diperiksa terhadap daftar field yang dapat diurutkan untuk entitas tersebut sebelum pemanggilan, karena backend diam-diam mengabaikan field yang tidak dapat digunakan untuk mengurutkan. Pada workspace yang sangat besar, backend menghapus pengurutan sepenuhnya; header akan memberi tahu jika itu terjadi.

dataset_item hanya dapat diurutkan sebagai perbandingan (dengan experiment_ids): endpoint items tidak menerima parameter pengurutan, jadi pengurutan pada daftar biasa ditolak alih-alih diabaikan.

Rentang waktu dan pencarian. trace, span dan thread menerima since dan until, masing-masing berupa rentang relatif ("30m", "1h", "7d") atau instan ISO-8601 dengan zona waktu, sehingga "satu jam terakhir" tidak memerlukan perhitungan waktu. Rentang waktu didasarkan pada waktu pembuatan rekaman, yang murah bagi backend dan sesuai dengan start_time dalam hitungan detik untuk lalu lintas langsung. Untuk batas yang tepat, masukkan start_time ke dalam filters. Ketiga tipe yang sama menerima search, teks bebas yang dicocokkan di mana saja dalam id, name, input, output, metadata, tags, dan thread id. Pencarian memindai seluruh proyek di backend, sehingga pemanggilan pertama pada proyek besar dapat memakan waktu puluhan detik. Pemanggilan tersebut mendapat batas waktu 60 detik. Menambahkan since membuatnya cepat kembali.

Membaca tabel. Durasi diberi label duration_ms / ttft_ms dan ditampilkan sebagai milidetik bulat; field tetap duration dalam filters dan sort. Stempel waktu ditampilkan hingga detik dan biaya sebagai desimal biasa. Baris proyek menyertakan last_updated_trace_at agar Anda dapat melihat proyek mana yang memiliki lalu lintas langsung; baris thread menyertakan pesan pertama. Halaman kosong dengan rentang waktu menyebutkan kapan trace terakhir proyek masuk, dan halaman kosong dengan source = "sdk" default menjelaskan cara melihat sumber lainnya. project_name yang salah eja akan mengembalikan nama terdekat yang ada.

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

Masalah Diagnostics. agent_insights_issue adalah halaman Diagnostics melalui MCP: kegagalan berulang yang dikelompokkan oleh tugas Diagnostics Opik untuk suatu proyek, diurutkan seperti di UI (yang paling baru terlihat lebih dahulu). Kolomnya adalah severity, status, total_occurrences (jumlah sepanjang waktu), latest_count (hari laporan terbaru, angka yang dirujuk oleh deskripsi masalah itu sendiri) dan last_seen. Masalah terbuka ditampilkan secara default; berikan status="resolved" atau "closed" untuk masalah lainnya. read dan list juga dapat dipanggil dengan issue, sebutan yang digunakan UI untuk masalah ini; nama panjangnya adalah yang ada dalam enum entity_type, sehingga entitas tersebut tidak muncul dua kali di sana. Jumlah dihitung sepanjang waktu agar cocok dengan UI; since / until yang sama seperti untuk trace mempersempit rentang waktu, yang dipotong ke hari laporan UTC karena Diagnostics mengagregasikan data per hari.

Daftar kosong menjelaskan alasannya, karena "tidak ada yang bermasalah" dan "Diagnostics belum diaktifkan" akan tampak sama jika tidak demikian. Ada lima status: Diagnostics tidak tersedia pada deployment ini, belum diaktifkan untuk proyek ini, dinonaktifkan, diaktifkan tetapi belum dipindai baru-baru ini, atau diaktifkan dan bersih beserta waktu pemindaian terakhir. Status yang dapat ditindaklanjuti menyebutkan pemanggilan yang perlu dilakukan, dan setiap status menautkan ke halaman Diagnostics proyek.

Daftar yang tidak kosong mencantumkan tanggalnya. Masalah yang ditampilkan adalah hasil pengelompokan dari pemindaian terakhir, jadi balasannya diakhiri dengan Report covers data through <time>, dan jika rentang waktu yang Anda minta melewati waktu tersebut, balasan menyebutkan bagian akhir yang belum tercakup dan cara menutupinya: pemicu saat pemindaian ulang menjangkau cukup jauh ke masa lalu, atau trace mentah dengan since yang diberikan. Jika Anda meminta data seminggu untuk proyek yang dipindai setiap malam, hari terakhir tidak ada dalam jawaban yang dikelompokkan; inilah yang menjelaskannya.

write("agent_insights_job.enable", {"project_name": "demo"}) mengaktifkan Diagnostics. Pemindaian harian dimulai sejak saat itu, dan pemanggilan ulang aman dilakukan. write("agent_insights_job.trigger", …) memindai 24 jam terakhir sekarang, tanpa menunggu pemindaian malam. Keduanya memerlukan izin yang sama dengan izin untuk membaca masalah, dan keduanya menolak permintaan jika deployment tidak menyediakan Diagnostics.

Masalah berpindah melalui siklus hidupnya dengan write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — ditangani — atau …close untuk masalah yang tidak perlu ditindaklanjuti, dan …reopen untuk mengembalikan keduanya ke daftar terbuka. Ketiganya memerlukan izin yang sama dan menjawab dengan tautan ke tampilan tempat masalah dipindahkan, karena masalah yang telah diselesaikan tidak lagi ada di halaman default. Menentukan apakah kegagalan sudah diperbaiki memerlukan pertimbangan, jadi lakukan ini hanya saat Anda memintanya: asisten tidak seharusnya merapikan daftar saat sedang melakukan triase.

Metrik dari waktu ke waktu. project_metric membuat grafik satu metrik untuk suatu proyek sebagai tabel bucket waktu: jumlah trace, span, dan thread, durasi, tingkat kesalahan, biaya, penggunaan token, dan skor umpan balik. Ini menjawab pertanyaan lanjutan setelah ikhtisar, yaitu kapan sesuatu berubah.

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

Baris adalah bucket waktu, bukan rekaman, jadi page, size dan sort ditolak alih-alih diabaikan. interval adalah hourly, daily, weekly atau total; jika tidak disertakan, nilainya mengikuti rentang waktu seperti tab Metrics — per jam hingga 3 hari, per hari hingga 30 hari, per minggu setelahnya — sehingga grafik default berisi beberapa lusin baris untuk rentang apa pun, sedangkan grafik bulanan per jam (721 baris) harus diminta secara khusus. since / until menggunakan format yang sama seperti di tempat lain dan default-nya adalah 7 hari terakhir. filters menggunakan field dari entitas yang terkait dengan metrik tersebut, jadi metrik span difilter berdasarkan field span.

breakdown membagi setiap bucket berdasarkan tags, name, error_info, error_type, model, provider, span_type, guardrail_name atau metadata.<key>. Tidak semua metrik menerima semua opsi tersebut, dan tujuh metrik tidak menerima opsi pengelompokan sama sekali; tool mengetahui opsi yang didukung dan memberi tahu sebelum memanggil backend, serta menyebutkan metrik yang menjawab pertanyaan sama jika ada. Tiga kelompok metrik menghasilkan beberapa seri sekaligus (durasi sebagai p50/p90/p99, skor umpan balik per nama, penggunaan token per kunci), dan saat dikelompokkan, backend hanya membuat grafik untuk satu seri dalam satu waktu, sehingga series= memilihnya: persentil, nama skor, atau kunci penggunaan. Durasi default-nya adalah p50 dan penggunaan token default-nya adalah total_tokens; nilai yang digunakan akan ditampilkan pada baris pertama.

Bucket kosong tidak ditampilkan dan jumlahnya dicantumkan di bawah, sehingga bulan yang sepi hanya menghasilkan beberapa baris, bukan kolom berisi nol, dan tingkat pada bucket tanpa trace tidak ditampilkan alih-alih dilaporkan sebagai nol.

Minta schema("list.project_metric") untuk tabel metrik, interval, dan matriks pengelompokan per metrik.

Nama-nama proyek. score_name mencantumkan nama skor umpan balik yang tercatat dalam proyek dan online_rule mencantumkan evaluator aturan otomatisasi yang dikonfigurasi di dalamnya, yang menjadi sumber sebagian besar nama tersebut. Keduanya adalah daftar yang sama dengan yang dibawa oleh read("project", …), secara lengkap dan berpaginasi, jika versi terbatas dalam ikhtisar tidak cukup.

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

write

Dispatcher penulisan universal. Berikan operation + data dan dispatcher akan memvalidasi payload, menerapkan verba REST yang sesuai, lalu mengembalikan respons backend.

Operasi:

Operasi	Fungsinya
trace.create	Mencatat satu trace (atau sekumpulan trace). Induk untuk span / skor / komentar.
trace.update	Menyelesaikan atau mengubah trace yang sudah ada.
span.create	Mencatat span pada trace yang sudah ada (atau sekumpulan span).
score.create	Melampirkan skor umpan balik numerik ke trace, span, atau thread.
comment.create	Melampirkan komentar teks bebas ke trace, span, atau thread.
prompt_version.save	Menyimpan versi prompt baru (membuat prompt berdasarkan nama jika belum ada).
dataset.create	Membuat dataset — type: "test_suite" menjadikannya rangkaian pengujian evaluasi.
dataset_item.upsert	Memasukkan atau memperbarui item dalam dataset (selalu menggunakan bentuk envelope).
experiment.create	Membuat eksperimen yang terkait dengan dataset.
experiment_item.create	Melampirkan baris trace + dataset_item ke eksperimen.
thread.close	Menutup thread (menandainya tidak aktif). Berikan thread_id dan proyek.
thread.open	Membuka kembali thread yang ditutup. Berikan thread_id dan proyek.
agent_insights_job.enable	Mengaktifkan Diagnostics untuk proyek (pemindaian harian, aman diulang).
agent_insights_job.trigger	Menjalankan pemindaian Diagnostics sekarang untuk 24 jam terakhir.
agent_insights_issue.resolve	Menandai masalah Diagnostics sebagai telah ditangani (tanyakan kepada pengguna terlebih dahulu).
agent_insights_issue.close	Menandai masalah Diagnostics sebagai tidak perlu ditindaklanjuti (tanyakan kepada pengguna terlebih dahulu).
agent_insights_issue.reopen	Mengembalikan masalah Diagnostics yang telah diselesaikan atau ditutup ke daftar terbuka.
annotation_queue.create	Membuat antrean anotasi proyek, dengan tampilan anotator khusus jika diinginkan.
annotation_queue.update	Mengubah antrean anotasi; menetapkan, mengganti, atau menghapus tampilan anotatornya.

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 field wajib dari operasi penulisan apa pun sebelum memanggilnya — berguna saat Anda tidak yakin seperti apa data. Mengembalikan skema, cakupan OAuth, dan satu contoh yang telah divalidasi. Hanya pencarian, tanpa pemanggilan backend.

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

Tool yang sama menjawab list.trace, list.span, list.thread dan list.experiment dengan referensi dari tool list untuk entitas tersebut: setiap field yang dapat difilter beserta tipenya dan operator yang valid, field yang dapat diurutkan, apakah rentang waktu dan pencarian teks bebas berlaku, serta dua contoh filter.

schema(operation="list.trace")

---

Konfigurasi

Pengaturan ini mengonfigurasi server lokal; setiap pengaturan adalah variabel lingkungan. Server yang di-host di Opik Cloud tidak menggunakan pengaturan ini.

Identitas / endpoint

Variabel	Default	Catatan
OPIK_API_KEY	—	Kunci API, untuk Comet yang di-host sendiri, atau untuk Opik Cloud tanpa server yang di-host. Opik sumber terbuka tidak memerlukannya kecuali deployment menambahkan autentikasi.
OPIK_WORKSPACE	unset	Nama workspace. Di cloud dengan kunci API, jika tidak disetel akan mengirim default, yang mengarah ke workspace default akun Anda — setel secara eksplisit jika Anda bekerja di workspace lain, atau pembacaan akan diam-diam menggunakan workspace yang salah. Biarkan tidak disetel saat menggunakan OAuth (token memuatnya) dan di lokal/OSS (default adalah satu-satunya workspace di sana).
COMET_WORKSPACE	—	Alias yang sudah usang untuk OPIK_WORKSPACE (kompatibilitas mundur). OPIK_WORKSPACE diutamakan jika keduanya disetel.
COMET_WORKSPACE_ID	unset	UUID workspace opsional. Disertakan dalam peristiwa analitik jika disetel, dan diutamakan daripada nilai yang telah ditentukan. Jarang diperlukan — instalasi OAuth mendapatkan UUID dari token secara otomatis.
COMET_URL_OVERRIDE	https://www.comet.com	Setel ke host Comet yang di-host sendiri, atau https://dev.comet.com untuk staging.
OPIK_URL	diturunkan dari COMET_URL_OVERRIDE + /opik/api	Setel untuk Opik sumber terbuka, yang menyediakan API-nya di /api (http://localhost:5173/api secara lokal). Di platform Comet, lakukan override hanya jika Opik berada di host/path yang berbeda dari UI Comet.
OPIK_DEFAULT_PROJECT_NAME	unset	Jika disetel, blob instructions per sesi memberi tahu LLM untuk meneruskan nilai ini sebagai project_name pada setiap pemanggilan tool, kecuali jika pengguna menyebutkan proyek lain.

Server / transport

Variabel	Default	Catatan
OPIK_MCP_TRANSPORT	stdio	stdio untuk peluncuran oleh host, streamable-http untuk mendengarkan pada port.
OPIK_MCP_HOST	127.0.0.1	Host bind uvicorn (streamable-http saja).
OPIK_MCP_PORT	8080	Port bind uvicorn (streamable-http saja).
OPIK_MCP_RELOAD	false	true untuk mengaktifkan --reload uvicorn (hanya dev).
OPIK_MCP_AS_URL	unset	URL Authorization Server 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 alur OAuth melalui HTTP.
OPIK_MCP_RESOURCE_URI	unset	URI publik kanonis server ini, diiklankan sebagai resource dalam metadata protected-resource dan digunakan untuk menurunkan petunjuk WWW-Authenticate.
OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S	30	Berapa lama jawaban "valid" dari introspeksi token opik-backend dipercaya sebelum permintaan berikutnya dengan token OAuth yang sama meminta validasi lagi. Membatasi beban backend akibat validasi per permintaan dan jangka waktu token yang kedaluwarsa masih diteruskan (jangka waktu itu juga berakhir saat backend pertama kali mengembalikan 401). Dibatasi oleh expires_at milik token jika backend melaporkannya.
OPIK_MCP_LOG_LEVEL	INFO	Ambang batas logger stderr.

Memilih transport

Dua bentuk bearer, dua kontrak untuk transport HTTP. Token akses OAuth opik_mcp_at_… divalidasi pada setiap permintaan terhadap endpoint introspeksi token opik-backend (di-cache, lihat OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S); token yang kedaluwarsa atau dicabut akan mendapat HTTP 401 dengan WWW-Authenticate: Bearer error="invalid_token", yang menjadi dasar host MCP untuk memulai pemberian refresh_token secara senyap. Kunci API Opik tidak divalidasi secara lokal: kunci tersebut diteruskan apa adanya ke opik-backend, yang menjadi satu-satunya titik penegakan. Pilih transport sesuai bentuk deployment:

Skenario	Transport
Opik Cloud	Tidak perlu menjalankan apa pun: server yang di-host adalah server ini melalui HTTP, dijalankan oleh Comet
Klien MCP dan Opik di mesin yang sama (instalasi OSS lokal)	stdio (disarankan — paling sederhana, tanpa port atau penyiapan OAuth)
Klien MCP lokal → Opik yang di-host sendiri	stdio dengan variabel lingkungan untuk deployment, atau HTTP dengan OAuth (OPIK_MCP_AS_URL mengarah ke backend)
opik-mcp disajikan di balik edge yang sama dengan opik-backend	HTTP — bearer divalidasi oleh backend pada setiap permintaan

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

Telemetri

Variabel	Default	Catatan
OPIK_MCP_ANALYTICS_ENABLED	true	Setel ke false untuk menonaktifkan semua telemetri non-Sentry.
`OPIK_MCP_SENTRY_ENABLED	true	Set to false untuk menonaktifkan semua telemetri Sentry.
=======

---

Batasan host yang diketahui

Host berbeda-beda dalam durasi yang diizinkan untuk satu pemanggilan tool:

• Claude Code — tidak ada batas waktu pemanggilan tool yang terdokumentasi. Disarankan.
• Cursor — batas waktu tetap 60s yang tidak direset saat ada progres (bug upstream).
• MCP Inspector — MAX_TOTAL_TIMEOUT membatasi durasi total (default 60s). Tingkatkan nilainya di UI Inspector untuk operasi yang lama.

Jika pemanggilan macet, setel OPIK_MCP_LOG_LEVEL=DEBUG untuk log permintaan lengkap.

---

Pemecahan masalah

Apakah penyiapan berfungsi? Jalankan server dengan env dari konfigurasi kliennya dan --check: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Server akan menyebutkan workspace dan proyek yang terlihat, atau memberi tahu apa yang perlu diperbaiki. Pesan kesalahan server juga menjelaskan perubahan yang perlu dilakukan dan menautkan ke halaman dokumentasi terkait.

OPIK_API_KEY tidak terbaca — variabel tersebut tidak diteruskan ke proses server. Di Claude Code / Cursor / VS Code, variabel lingkungan hanya berlaku jika berada di dalam blok env pada konfigurasi server MCP, bukan di shell Anda; Codex juga meneruskan nama-nama yang tercantum di env_vars. Mulai sesi baru setelah mengedit, karena klien membaca konfigurasi saat sesi dimulai.

Permintaan menuju /opik/api pada Opik sumber terbuka — COMET_URL_OVERRIDE ditujukan untuk platform Comet yang di-host sendiri. Opik sumber terbuka menyediakan API-nya di /api: setel OPIK_URL=http://localhost:5173/api (atau https://<host>/api) sebagai gantinya. Server akan memberi peringatan saat startup jika host-nya adalah mesin ini, dan --check menjawab "Tidak ada API Opik di …".

Pemanggilan Cursor kehabisan waktu setelah 60s — ini bug Cursor yang diketahui, bukan opik-mcp. Persempit pemanggilan (gunakan size yang lebih kecil atau rentang waktu yang lebih sempit), atau jalankan operasi yang sama di Claude Code yang tidak memiliki batas tetap.

Server tidak muncul, proses masuk tidak terbuka, workspace salah, uvx tidak ditemukan. Semua ini dibahas di bagian pemecahan masalah dalam dokumentasi. uvx opik@latest mcp status mencantumkan setiap klien yang telah dikonfigurasi dengan server dan menunjukkan apakah konfigurasinya telah menyimpang.

---

Pengembangan

git clone git@github.com: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

Target umum:

Target	Fungsinya
make install	uv sync --locked --extra dev
make run	Jalankan server MCP (stdio secara default).
make run-dev	Jalankan dengan logging DEBUG + --reload uvicorn.
make dev	Jalankan melalui mcp dev (wrapper mode dev Inspector).
make inspect	Luncurkan MCP Inspector terhadap server yang sedang berjalan.
make test	uv run pytest -q.
make lint	ruff check + pemeriksaan format.
make format	ruff format + ruff check --fix.
make typecheck	mypy.
make check	lint + typecheck + test.

Struktur repo:

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

---

Bantuan

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

---

Lisensi

Apache-2.0.