Comet Opik

resmi

Opik günlüklerinizi, izlemelerinizi, istemlerinizi ve LLM'lerinizden gelen diğer tüm telemetri verilerinizi doğal dilde sorgulayın ve analiz edin.

GitHub

226

Comet Opik MCP ile neler yapabilirsiniz?

Projeye göre izleri sorgulayın — Bir projede bugün hangi izlerin başarısız olduğunu; hata bilgisi, süre veya token kullanımı filtreleriyle sorun.
Herhangi bir Opik varlığını okuyun — Bir projeyi, izi, aralığı, veri kümesini, deneyi, istemi, ileti dizisini veya Diagnostics sorununu kimliğe, ada ya da opik:// URI'sine göre alın.
Puan ve yorum kaydedin — Yazma aracı üzerinden bir izi, gerekçesiyle birlikte bir geri bildirim metriğine göre puanlayın veya yorum ekleyin.
İstem sürümlerini kaydedin — Veri kümeleri ve deneylerin yanında yeni istem sürümleri oluşturup kaydedin.
Yazma şemalarını inceleyin — Geçerli bir yük oluşturmadan önce bir yazma işleminin şemasını sorun.
Proje sağlığını kontrol edin — Son 7 günün iz sayısını, hata oranını, ortalama süreyi ve toplam maliyeti öğrenmek için bir projeyi okuyun.

Dokümantasyon

Opik MCP Sunucusu

Comet tarafından geliştirilen, açık kaynaklı LLM gözlemlenebilirlik ve değerlendirme platformu Opik için resmi Model Context Protocol (MCP) sunucusu. Yapay zekâ ana makinenizi (Claude Code, Cursor, VS Code Copilot, Codex, opencode veya herhangi bir MCP istemcisi) doğrudan Opik çalışma alanınıza bağlayın: izleri okuyun, puanları kaydedin ve istem sürümlerini sohbetten kaydedin.

Opik'i zaten kullanan ve onu kod yazdığı yapay zekâ asistanından yönetmek isteyen LLM mühendisleri için geliştirildi.

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

Hızlı başlangıç

Tek bir komut, Claude Code dahil olmak üzere makinenizdeki yapay zekâ istemcilerinde Opik'i kurar. Opik'inizi bulur (~/.opik.config içinde kayıtlı olanı, localhost'ta çalışanı veya hangisi olduğunu sorar), MCP sunucusunu kaydeder, Opik beceri paketini yükler ve bağlantıyı denetler. Opik Cloud'da yönetmeniz gereken bir API anahtarı yoktur: istemciniz tarayıcıda oturum açar. uv gerekir, Opik SDK'sı gerekmez:

uvx opik@latest mcp configure

Bir kodlama aracısından veya betikten olduğu gibi terminal kullanmadan kurulum yapmak için istemciyi belirtin:

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

--ai-client ayrıca codex, cursor, vscode ve opencode değerlerini de kabul eder. Bu şekilde çalıştırıldığında ~/.opik.config içinde kayıtlı Opik'i (API anahtarı dahil) veya localhost'ta yanıt veren Opik'i kullanır; bunların hiçbiri yoksa durur ve --deployment için sorar.

"install opik mcp" isteği alan bir kodlama aracısı, kullanıcıya sorulacaklar da dahil olmak üzere tüm adımları uvx opik-mcp@latest --help üzerinden alır. Bunlar aşağıdaki Kodlama aracısıyla yükleme bölümündeki adımlarla aynıdır.

Sunucuyu, Elle kurulum bölümündeki istemci komutlarıyla elle kaydetmek, hangi Opik'i kullandığınızı denetleme ve beceri paketini yükleme adımlarını atlar; bu nedenle yalnızca yükleyicinin desteklemediği istemciler içindir.

Opik'iniz	Sunucu	Aktarım	Oturum açma
Opik Cloud (`www.comet.com`)	barındırılan sunucu, Comet tarafından işletilir	Streamable HTTP	tarayıcıda (OAuth); API anahtarı gerekmez
Kendi sunucunuzda barındırılan Comet, açık kaynaklı Opik	yerel sunucu, bu paket	stdio	ortam değişkenleri; yalnızca dağıtım gerektiriyorsa API anahtarı

İstemciler MCP sunucularını oturum başlarken yükler; bu nedenle sonrasında yeni bir oturum başlatın.

Kurulum kılavuzu, sorun giderme ve SSS: comet.com/docs/opik/mcp-server.

Opik Cloud: barındırılan sunucu

Comet, sunucuyu https://www.comet.com/opik/api/v1/mcp adresinde çalıştırır. İstemciniz HTTP üzerinden bağlanır ve ilk seferinde tarayıcıda oturum açma sayfasını açar. Yüklenecek bir şey, API anahtarı veya ayarlanacak çalışma alanı yoktur: sunucu, oturum açarken seçtiğiniz çalışma alanında çalışır. Ekledikten sonra yeni bir oturum başlatın ve şunu sorun: "list my Opik projects".

Hızlı başlangıç komutu, beceri paketiyle birlikte Claude Code, Codex, Cursor, VS Code Copilot ve opencode için kurulumu yapar. Claude Code'da eklenti aynı işlemi tek komutla yapar. Aşağıdaki düğmeler Cursor veya VS Code'a tek tıklamayla ekler; elle kaydetmenin diğer yolları için Elle kurulum bölümüne bakın.

Claude Code eklentisi

opik eklentisi Opik becerilerini yükler ve Opik Cloud için barındırılan MCP sunucusunu kaydeder:

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

2.1.275 öncesi Claude Code sürümlerinde önce /plugin marketplace add comet-ml/opik-mcp, ardından /plugin install opik@opik komutunu çalıştırın. Beceriler opik:<skill> olarak yüklenir; örneğin opik:opik-instrument. /mcp sunucuyu plugin:opik:opik-cloud olarak gösterir. Sunucu Opik Cloud'a aittir. Yeni bir oturum başlatın, ardından /mcp → Authenticate üzerinden oturum açın. MCP OAuth sunucusunu çalıştıran, kendi sunucunuzda barındırılan bir Comet için claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp ile ekleyin; kendi sunucunuzda barındırılan veya açık kaynaklı diğer Opik kurulumları için Hızlı başlangıç komutunu kullanın. Ardından /mcp içinde plugin:opik:opik-cloud seçeneğini devre dışı bırakın. Claude Code, bu pazaryerindeki bir eklentiyi kendiliğinden güncellemez: /plugin marketplace update opik komutunu, ardından /plugin update opik@opik komutunu çalıştırın veya pazaryeri için otomatik güncellemeyi /plugin içinde etkinleştirin. Bu pazaryeri, son sürümden daha güncel olabilen main sürümünü sunar. Güncelleme yalnızca her sürümde eklentinin sürümü değiştiğinde gelir.

Daha önce aynı URL'de opik-mcp eklediyseniz Claude Code sizin kopyanızı korur ve eklenti kopyasını atlar. Sizinki yerel uvx opik-mcp gibi başka bir sunucuysa ikisi de yüklenir: yalnızca eklentidekini tutmak için claude mcp remove opik-mcp komutunu çalıştırın. Beceri paketindeki beceriler de eklentidekilerin yanında yüklenir; hangilerinin kaldırılacağını soran npx skills remove --global --agent claude-code ile bunları kaldırın.

Kendi sunucunuzda barındırılan ve açık kaynaklı Opik: yerel sunucu

opik-mcp makinenizde çalışır: istemci onu uvx opik-mcp ile başlatır ve stdio üzerinden iletişim kurar. Hızlı başlangıç komutu, ~/.opik.config içindeki Opik'inizden veya yerel bir Opik'ten kurulumu yapar; elle kaydetmek için Elle kurulum bölümüne bakın. uv paketini bir kez yükleyin; ilk kullanımda paketi ve gerekirse Python 3.13'ü getirir:

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

uvx opik-mcp, uv'nin önbelleğe aldığı kopyayı yeniden kullanır; bu nedenle hızlı başlar; uv cache clean opik-mcp ise sonraki başlangıçta en yeni sürümü getirir. uvx opik-mcp@latest her başlangıçta PyPI'ye sorar; bu da yaklaşık bir buçuk saniye ekler. Codex, ilk araç listesini oluşturmadan önce sunucular için varsayılan olarak 1 saniye olan mcp_optional_startup_grace_ms kadar bekler; bu nedenle yavaş bir başlangıç, araçların ilk turda görünmemesine yol açabilir. Bu README'deki tek seferlik komutlarda (opik mcp configure, opik mcp status, --help, --check) @latest bulunur; böylece uv'nin aylar önce önbelleğe aldığı bir kopya hiçbir zaman çalıştırılmaz.

Ortam değişkenleri sunucuyu Opik'inize yönlendirir:

Opik'iniz	Ortam değişkenleri
Bu makinedeki açık kaynaklı Opik	`OPIK_URL=http://localhost:5173/api`
Sunucudaki açık kaynaklı Opik	`OPIK_URL=https://<host>/api`; yalnızca dağıtım kimlik doğrulaması ekliyorsa `OPIK_API_KEY`
Kendi sunucunuzda barındırılan Comet platformu (Opik kullanıcı arayüzü `https://<host>/opik` adresinde)	`COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY`

Açık kaynaklı sürüm API'sini /api adresinde sunar ve default adlı tek bir çalışma alanına sahiptir; bu nedenle OPIK_WORKSPACE gerekmez. COMET_URL_OVERRIDE, sunucuyu /opik/api adresine yönlendirir; açık kaynaklı sürüm bu adresi sunmaz.
Kendi sunucunuzda barındırılan Comet'in adlandırılmış çalışma alanları vardır. OPIK_WORKSPACE değerini, Opik URL'nizde /opik/ sonrasındaki bölüme ayarlayın; belirtilmezse okumalar hesabınızın varsayılan çalışma alanından yapılır ve bu durum için hata verilmez.
MCP OAuth sunucusunu çalıştıran (varsayılan olarak kapalı) kendi sunucunuzda barındırılan bir Comet, bunun yerine barındırılan akışı https://<host>/opik/api/v1/mcp adresinde kullanabilir.
Her değeri değiştirin. Sunucu, <your-workspace> veya ${input:OPIK_WORKSPACE} gibi yer tutucu çalışma alanlarını reddeder; yer tutucu URL olduğu gibi gönderilir ve bağlantı kurulamaz.
env bloğundaki OPIK_MCP_ANALYTICS_SOURCE="", kendi sunucunuzda barındırılan bir kurulumun telemetri olaylarında bulut Comet kaynak etiketini kullanmamasını sağlar.

Sunucuyu bir istemciye eklemeden önce ayarları denetleyin: aynı ortam değişkenleri ve --check ile çalıştırın. Opik'e bir çağrı yapar ve çalışma alanını, gördüğü proje sayısını veya düzeltilecekleri belgelerin bağlantısıyla birlikte yazdırır; ardından 0 ya da 1 koduyla çıkar. İstemci bunu yeni bir oturumdan önce size bildiremez: Claude Code yanlış anahtarla bile Connected gösterir, Codex ise o zamana kadar hiçbir şey başlatmaz.

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

Ardından istemcinize kaydedin: yerel sunucuyu elle kurma.

Kodlama aracısıyla yükleme

"install opik mcp" gibi bir istekle sunucuyu yüklemesi istenen bir yapay zekâ aracısı için. Amaç, sunucunun kullanıcının Opik'i için kaydedilmesi, Opik beceri paketinin yüklenmesi ve kullanıcının oturum açmış olmasıdır. Bu makinedeki Opik'in hangisi olduğunu belirleyin ve yalnızca bilemeyeceğiniz şeyleri kullanıcıya sorun: her mesajda tek soru sorun ve sonraki soruya geçmeden önce yanıtı bekleyin. 3. adımdaki yükleyici tüm kurulumu tek çalıştırmada yapar; bu nedenle çalıştırmadan önce 1. ve 2. adımları tamamlayın. uvx opik-mcp@latest --help bu adımları yazdırır.

Neler olduğunu görün.
```
uvx opik@latest mcp status
```
~/.opik.config içinde kayıtlı Opik'i (URL ve çalışma alanı, anahtar asla gösterilmez) ve sunucunun zaten kayıtlı olduğu istemcileri gösterir. Claude Code'da ayrıca claude mcp list komutunu çalıştırın: claude.ai bağlayıcılarını ve diğer adlar altındaki girdileri gösterir. Her girdinin komutunu da yazdırır; eski bir npx girdisi API anahtarı içerebilir: bunu tekrar etmeyin.
- Herhangi bir ad altında, örneğin claude.ai bağlayıcısı olarak https://www.comet.com/opik/api/v1/mcp için bir sunucu varsa kayıtlı demektir: ikinci bir tane eklemeyin. Beceri paketini tek başına npx skills add comet-ml/opik-skills -g --all ile yükleyin. Sunucu ! Needs authentication olarak görünüyorsa 4. adıma geçin.
- Yükleyici, eski npx sunucusu gibi mevcut bir opik-mcp girdisini sormadan değiştirir. Çalıştırmadan önce kullanıcıya sorun.
Kullanıcının Opik'ini bulun.
- ~/.opik.config içinde kayıtlıysa onu kullanın ve kullanıcıya hangisini kurduğunuzu söyleyin. Yükleyici, API anahtarı dahil kayıtlı yapılandırmayı okur; bu nedenle anahtar sormayın.
- ~/.opik.config yoksa: curl -s http://localhost:5173/api/is-alive/ping. Yanıt, bu makinede çalışan açık kaynaklı bir Opik olduğu anlamına gelir. Codex'inki gibi korumalı bir kabukta yanıt alınamaması, Opik olmadığı değil, kabuğun ağa erişemediği anlamına gelebilir.
- İkisi de yoksa sorun ve kendiniz seçim yapmayın. Projedeki .env içinde OPIK_URL_OVERRIDE gibi bir Opik URL'si varsa, evet-hayır sorusu sorun. Aksi takdirde: "Hangi Opik'i kullanıyorsunuz: Opik Cloud (www.comet.com), açık kaynaklı bir Opik (URL'si) veya kendi sunucunuzda barındırılan bir Comet platformu (URL'si ve çalışma alanı)?"

Çalıştığınız istemci için yükleyiciyi çalıştırın. Opik beceri paketini sunucuyla birlikte, --skills olsun ya da olmasın yükler; kullanıcıya daha sonra çalıştırması için vereceğiniz komutta bu bayrağı koruyun. Opik Cloud'da tarayıcıda oturum açma sayfasını açar ve bir dakika bekler; bu nedenle önce kullanıcıya haber verin.

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

--ai-client ayrıca codex, cursor, vscode ve opencode değerlerini de kabul eder. Opik ~/.opik.config içinde kayıtlıysa veya localhost'ta çalışıyorsa komutu olduğu gibi çalıştırın: --deployment kayıtlı yapılandırmayı (API anahtarı dahil) kenara alır. İkisi de yoksa 2. adımda kullanıcının belirttiği Opik için bayrağı ekleyin:

Kullanıcının Opik'i	Eklenecek
Opik Cloud, `www.comet.com`	`--deployment cloud`
Açık kaynaklı Opik	`--deployment local`; localhost'ta değilse `--url <url>`
Kendi sunucunuzda barındırılan Comet platformu, URL'sinde `/opik/`	`--deployment self-hosted --url <url> --workspace <workspace>`; kabukta `OPIK_API_KEY` ile

Opik yanıt vermediğinde olduğu gibi başarısız olursa, kullanıcıya yazdırılanları ve VPN'i veya URL'yi denetlemek gibi neleri kontrol etmesi gerektiğini söyleyin. Başka bir Opik'e geçmeyin.

Opik Cloud için oturum açma. Yükleyici sunucunun henüz oturum açmadığını bildirirse, tarayıcıda beklediği için kullanıcıya kendiniz çalıştırmak yerine claude mcp login opik-mcp komutunu veya Claude Code oturumunda /mcp komutunu çalıştırmasını söyleyin. claude.ai bağlayıcısında oturum açma işlemi /mcp üzerinden yapılır. Oturum açarken bir çalışma alanı seçilmesi istenir; varsa ~/.opik.config içinde kayıtlı olanı belirtin.
Tamamlayın. Nelerin yüklendiğini ve nelerin kaldığını söyleyin. Beceri paketinin adını belirtin: her proje için yüklenen Opik becerileri, aracıya Opik ile araçlandırma, değerlendirme ve hata ayıklama yapmayı öğretir. İstemciler MCP sunucularını ve becerileri oturum başlarken yükler: kullanıcıdan yeni bir oturum başlatmasını isteyin, ardından "list my Opik projects" komutunu denesin.

Her durumda:

Kullanıcıdan sohbet içine API anahtarı yapıştırmasını istemeyin. Barındırılan sunucu anahtar gerektirmez; aksi durumda anahtarı kabuk ortamından ("$OPIK_API_KEY") alın veya komutu kullanıcının çalıştırmasını sağlayın.
Çalışma alanını tahmin etmeyin. Kullanıcının Opik URL'sinde comet.com/opik/ (veya kendi sunucusunda barındırılan Comet'te /opik/) sonrasındaki bölümdür.
~/.claude.json veya ~/.opik.config değerlerini yazdırmayın: ikisi de API anahtarı içerebilir. uvx opik@latest mcp status ve claude mcp list gereken bilgileri gösterir; yükleyici yapılandırmayı kendisi okur.
Bir izin denetimi komutu engellerse bunu aşmaya çalışmayın. Kullanıcıya çalıştırması için komutu verin (Claude Code'da çalıştırmadan önce !). Kurucunun bilmediği bir istemci için, Elle kurulum bölümündeki komutlarla elle kaydedin: Opik Cloud için barındırılan sunucuyu, diğerleri için yerel sunucuyu.
Yerel sunucuyu kaydetmeden önce, kullanacağınız ortam değişkenleriyle ve --check ile çalıştırın; OPIK_API_KEY komuta yazmak yerine kabukta dışa aktarılmış olsun: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Komut 0 koduyla çıkar ve gördüğü çalışma alanının adını verir ya da düzeltilmesi gerekenleri yazdırır. Kayıt tamamlandıktan sonra Claude Code, anahtar yanlış olsa bile Connected bildirir; Codex'te ise kontrol yoktur.
Claude Code, mevcut bir opik-mcp girdisinin üzerine yazmayı reddeder; bu nedenle önce claude mcp remove opik-mcp --scope user ile kaldırın. Codex'in add komutu ise girdinin yerini alır.
Kaydettikten sonra Claude Code'da yalnızca durum satırını okuyun: claude mcp get opik-mcp | grep Status. Tam çıktı, API anahtarı da dahil olmak üzere env bloğunu yazdırır. Barındırılan sunucu, claude mcp login opik-mcp çalıştırılana kadar ! Needs authentication gösterir. Codex'te oturum başlamadan önce sunucuyu başlatan bir komut yoktur; codex mcp get opik-mcp kaydedilenleri gösterir ve ortam değişkeni değerlerini maskeler.

Elle kurulum (Opik kontrolü yok, beceri paketi yok)

Hızlı başlangıç komutu Claude Code, Codex, Cursor, VS Code Copilot ve opencode için bunların tümünü yapar; ayrıca hangi Opik'i kullandığınızı kontrol eder ve beceri paketini yükler. Yalnızca başka bir istemci için veya kurucunun ne yazdığını görmek için elle kaydedin. Kullanıcı adına kurulum yapan bir kodlama aracısı kurucuyu çalıştırır: bkz. Bir kodlama aracısıyla kurulum.

Barındırılan sunucu (Opik Cloud)

Claude Code, elle

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

Ardından bir Claude Code oturumunda /mcp → Authenticate üzerinden oturum açın. Tarayıcı açılır; klavyenin başındaki kişi bu işlemi yapar. Kendi terminalinden claude mcp login opik-mcp aynı işi yapar. --scope user sunucuyu her projede kullanılabilir kılar; bu seçenek olmadan Claude Code sunucuyu yalnızca geçerli dizin için kaydeder. SSH üzerinden claude mcp login opik-mcp --no-browser, kendi makinenizde açmanız için oturum açma URL'sini yazdırır; son adım etkileşimli bir terminal gerektirir (ssh -t).

Codex, elle

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

add oturum açma penceresini açar; codex mcp login opik-mcp pencereyi yeniden açar. ~/.codex/config.toml içinde aynı sunucu şöyle tanımlanır:

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

Cursor, elle

Barındırılan sunucunun altındaki düğmeyi kullanın veya ~/.cursor/mcp.json dosyasına ekleyin:

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

VS Code Copilot, elle

Barındırılan sunucunun altındaki düğmeyi kullanın veya çalışma alanınızdaki .vscode/mcp.json dosyasına ya da kullanıcı mcp.json dosyanıza ekleyin (MCP: Open User Configuration):

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

Diğer istemciler

URL kabul eden tüm istemciler barındırılan sunucuyu kullanabilir:

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

Yalnızca yerel komutları başlatabilen bir istemci, sunucuya npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp üzerinden erişebilir.

API anahtarıyla Opik Cloud

Bir aracının betikten gözetimsiz çalışması veya istemcinin MCP OAuth desteği olmaması gibi durumlarda tarayıcı üzerinden oturum açmak mümkün değilse, bunun yerine comet.com/api/my/settings/ adresinden bir API anahtarı kullanın ve yerel sunucuyu Opik Cloud'a yönlendirin:

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

Diğer istemciler de env bloklarında aynı iki değişkeni alır. OPIK_WORKSPACE değerini Opik URL'nizde comet.com/opik/ sonrasındaki bölüme ayarlayın (https://www.comet.com/opik/acme-ai/projects → acme-ai). Bu değer belirtilmezse sunucu default gönderir; Comet bunu hesabınızın varsayılan çalışma alanına çözümler. Böylece hata almadan yanlış çalışma alanından veri okunabilir.

Yerel sunucu (kendi barındırdığınız ve açık kaynaklı Opik)

Örneklerde yerel, açık kaynaklı Opik kullanılır. Kendi barındırdığınız Comet için tablodaki üç değişkeni kullanın. Sunucuyu ekledikten sonra yeni bir oturum başlatın ve şunu sorun: "Opik projelerimi listele".

Claude Code, elle

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

Kendi barındırdığınız Comet'te, anahtar kabuğunuzdaki OPIK_API_KEY içindeyken:

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

Ya da ~/.claude.json dosyasını doğrudan düzenleyin:

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

Sunucu başladığında claude mcp get opik-mcp, ✔ Connected gösterir. Bu, URL'nin veya anahtarın doğru olduğunu kanıtlamaz; çünkü Opik'e yalnızca bir araç çağrısı ulaşır. Bunu --check (yerel sunucu) yapar. Ayrıca API anahtarı da dahil olmak üzere env bloğunu yazdırır.

Codex, elle

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

Ya da ~/.codex/config.toml dosyasını düzenleyin:

[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, yerel sunucuya yalnızca env içindeki değişkenleri ve env_vars içindeki adları verir. Bu nedenle kabuğunuzda dışa aktarılan bir anahtar başka şekilde sunucuya ulaşmaz.

Cursor, elle

~/.cursor/mcp.json (genel) veya .cursor/mcp.json (proje) dosyasına ekleyin ya da Cmd+Shift+J → Features → Model Context Protocol yolunu kullanın:

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

Cursor 60s zaman aşımı. Cursor, ilerleme bildirimleriyle sıfırlanmayan katı bir araç çağrısı zaman aşımı uygular. Bkz. Bilinen ana makine sınırları.

VS Code Copilot, elle

Çalışma alanınızdaki .vscode/mcp.json dosyasına veya kullanıcı mcp.json dosyanıza ekleyin (MCP: Open User Configuration):

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

MCP Inspector (elle test)

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

`npx opik-mcp` kullanıyorsanız

TypeScript sunucusu (npm opik-mcp@2) kullanımdan kaldırılmıştır ve 2026-11-15 tarihinde isteklere yanıt vermeyi durduracaktır. Yeni bir kurulum için Hızlı başlangıç komutunu çalıştırın; uvx opik-mcp, kurucu değil, istemcinin sunucuyu başlatmak için çalıştırdığı komuttur. Opik Cloud'daki mevcut bir yapılandırmayı taşımak için barındırılan sunucuya geçin ve API anahtarını kaldırın. Aksi takdirde MCP istemcisi yapılandırmanızda npx -y opik-mcp yerine uvx opik-mcp yazın. Bazı ortam değişkenlerinin adı değişti ve komut satırı işaretleri artık okunmuyor: https://github.com/comet-ml/opik-mcp/blob/main/legacy/typescript/MIGRATION.md bakın. Destek politikası: DEPRECATED.md. TypeScript kaynak kodu git etiketi legacy-typescript-final konumundadır.

Araçlar

opik-mcp, tüm yaşam döngüsünü (oku → açıklama ekle → düzenle → oluştur → yinele) kapsayan, sonuç odaklı küçük bir arayüz sunar.

Araç	Amaç
`read`	Kimliğe / ada / `opik://` URI'sine göre evrensel okuma
`list`	İsteğe bağlı ad filtresi ve sayfalama ile evrensel listeleme
`write`	Evrensel yazma — izleri/aralıkları kaydetme, puanlama, yorum yapma, istemleri kaydetme, veri kümelerini ve deneyleri yönetme
`schema`	Yazma işlemi şemalarını inceleme (LLM'nin geçerli yükler oluşturması için kullanılır)
`read_skill`	Bu sunucuyla birlikte gelen Opik aracısı becerilerinden birini okuma

`read`

Her türlü "bana X'i göster" sorusu için tek araç. Bir entity_type ile birlikte id (UUID veya adlandırılabilir türler için ad) ya da tam bir opik:// URI'si alır. Bileşik okumalar (trace, prompt, thread, agent_insights_issue) alt öğelerini satır içinde içerir; böylece tek çağrı tüm resmi sunar.

Adını verdiğiniz kayıt bütünüyle döner. Satır içinde yer alan alt öğeler ise bütünüyle dönmez: içerikleri arka ucun truncate=true değeriyle alınır. Bu nedenle ClickHouse'ta ~10 KB'ı aşan bir alan kesilir ve base64 görüntüler "[image]" ile değiştirilir. Aksi hâlde 200 aralıkta yinelenen tek bir ek, okumanın geri kalanından daha fazla maliyete yol açabilir. Yanıtta bu durum spanBodies / messageBodies içinde belirtilir. Herhangi bir alt öğe, truncate parametresi hiç bulunmayan uç noktalara giden kendi read("span", id) veya read("trace", trace_id) çağrısıyla yeniden bütünüyle alınabilir.

Satır içinde yer alan koleksiyonların uzunluğu da sınırlıdır: 200 aralık, 200 tur, 100 istem sürümü. Bu sınır aşıldığında spansTruncated / messagesTruncated / versionsTruncated, true olur; yanındaki moreSpans / moreMessages / moreVersions satırı ise sayıyı ve satır içinde yer alan bölümün kaldığı yerden devam eden tam list(...) çağrısını içerir.

Desteklenen varlıklar: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. project, experiment, prompt, dataset için ada göre arama kullanılabilir (daha yavaştır — iki API çağrısı yapar — ve birden fazla eşleşme döndürebilir). thread ve agent_insights_issue proje kapsamındadır: project_id veya project_name ya da projeyi içeren bir bağlantı/URI iletin. dataset ve dataset_item daha önce test_suite ve test_suite_item olarak adlandırılıyordu. Eski adlar hâlâ çalışır, ancak önerilmez; yeni kodda yeni adları kullanın.

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 kullanıcı arayüzünden kopyalanan bir bağlantı, id olarak kullanılabilir: bir iş parçacığı bağlantısı veya Diagnostics sayfası bağlantısı projeyi içerir; bu nedenle project_id gerekmez ve varlık türü bağlantıdan alınır.

project okuması, "projem nasıl gidiyor?" sorusunu tek çağrıda yanıtlar. {project, summary, vocabulary, contains, url} döndürür: önce kayıt, ardından Logs sayfasında kart olarak gösterilen dört ölçüm (iz sayısı, hata oranı, ortalama süre, toplam maliyet). Ekrandaki gibi, yalnızca SDK trafiği için son 7 günü önceki 7 günle karşılaştırır. since / until bu zaman aralığını değiştirir; since="30d" ise kullanıcı arayüzünün açtığı değerdir. İz bulunmayan bir dönemin oranı veya ortalaması null olarak döner; çünkü trafiğin olmadığı bir haftada %0 hata görülmesi, haftanın sorunsuz geçtiği anlamına gelmez.

vocabulary, başka bir şey sormadan önce gereken haritadır: projenin geri bildirim puanı adları, belirteç kullanımı anahtarları ve izleri puanlayan otomasyon kuralları. Bunlar, filtrede veya aşağıdaki series= içinde kullanılan adlardır. Tahmin ederek girilen adlar, iyi haber gibi görünen boş bir sayfa döndürür. Puan adları ve kurallar sınırlıdır; gerçek toplamı her zaman bildirir ve geri kalanını getiren çağrıyı belirtir. Kullanım anahtarları ise başka hiçbir yerde listelenmediğinden eksiksiz olarak verilir. contains, en yeni deneyi, veri kümesini, istem sürümünü ve optimizasyon çalıştırmasını belirtir; böylece "burada neler oluyor?" sorusu için dört ek çağrı gerekmez. Yüklenemeyen bir bölüm boş görünmek yerine bunu belirtir; boş bölümler ise atlanır.

Bir agent_insights_issue okuması {issue, example_trace_ids, details} döndürür: Diagnostics sorun kaydı (ad, açıklama, neden, önerilen düzeltme, önem derecesi, durum), sorunu gösteren tekilleştirilmiş iz kimlikleri (Diagnostics sayfasında gösterilen örnek; birini read("trace", id) ile açın) ve gün bazında döküm. İz içerikleri satır içinde yer almaz; böylece okuma tek bir arka uç çağrısında kalır. since / until gün bazındaki satırları daraltır; varsayılan olarak tüm zamanlar kullanılır. Sunucu Opik URL'sini ve oturumun çalışma alanını biliyorsa okuma ayrıca url (sorunun Diagnostics sayfası) ve trace_url_template (örnek izlerden herhangi biri için derin bağlantı) içerir; böylece asistan tıklanabilir bir bağlantı sunabilir. Çalışma alanı çözümlenemeyen bir OAuth oturumunda bağlantılar tahmin edilmek yerine atlanır.

İzlerin kendileri URL içermez. Bir iz için bağlantı, read veya list tarafından döndürülen alanlardan türetilemez; tahmin edilen bir biçim 404 hatası verir. Bunun yerine oturum yönergeleri bir şablon belirtir: .../v1/session/redirect/projects/?trace_id={trace_id}&path=.... Böylece asistan bir kimlik ekleyip size bağlantı sunar. Bağlantı, opik-backend'in yönlendirmesinden geçer; proje ve çalışma alanı izden çözümlenir. Bu nedenle doğrudan proje URL'sinin çalışmadığı yerlerde, çalışma alanı çözümlenemeyen bir OAuth oturumu da dahil olmak üzere, çalışır. Python SDK'sının bir iz için yazdırdığı bağlantıyla aynıdır.

`list`

Sayfalama kullanarak bir koleksiyona göz atın veya koleksiyonda arama yapın. Proje kapsamındaki türler (trace, span, thread, agent_insights_issue, dataset_item, prompt_version) üst öğelerini gerektirir: bir proje UUID'si veya adı, bir veri kümesi UUID'si ya da bir istem UUID'si.

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

Filtreler. trace, span, thread, experiment ve dataset_item, SDK'nın search_traces(filter_string=…) dilbilgisiyle aynı OQL dizgesini alır:

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

Dizeler çift tırnak içinde, sayılar tırnaksızdır; duration milisaniye cinsindendir, tarihler saat dilimi içeren ISO-8601 anlarıdır ("2026-09-08T10:00:00Z"). Puanlar ve sözlükler bir anahtar alır: feedback_scores.accuracy < 0.5, metadata.environment = "prod". Tek bağlayıcı AND'tir.

Arayüzdeki Logs sayfasında olduğu gibi, iz, span ve thread listelerine source = "sdk" eklenir; böylece değerlendirici, playground ve deney izleri görünümü kalabalıklaştırmaz; bunları görmek için source adını kendiniz belirtin. İlk çıktı satırı uygulanan filtreyi yansıtır.

Hatalı bir filtre, düzeltilmesi için gereken bilgilerle birlikte backend'e ulaşmadan başarısız olur: sözdizimi hatasının konumu, en yakın alan adı, alanın türü için geçerli operatörler veya beklenen değer biçimi. Kapalı bir değer kümesine sahip alanlar (source, span type, thread status, visibility_mode) de bu kümeye göre denetlenir; in listesindeki her öğe de buna dahildir. source, backend'in kendi doğruladığı tek alandır ve bilinmeyen bir değere 400 yerine 500 yanıtı verir; bu nedenle büyük harf içeren bir source = "SDK" aksi hâlde anlaşılması güç bir sunucu hatasına yol açardı. Diğerleri dizeler olarak karşılaştırılır ve boş bir sayfayla yanıtlanır; bu da "böyle bir değer yok" anlamına geldiğinde "eşleşme yok" gibi görünür. Tam alan başvurusu ve kabul edilen değerler için schema("list.trace") (veya list.span, list.thread, list.experiment) isteyin.

Bir veri kümesinde tek bir örneği bulma. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key>, veri kümesinin oluşturulduğu anahtarları; full_data, tüm yük içinde bir alt dizeyi (tam tarama — mümkünse bir anahtar belirtin); ayrıca id, tags, source, trace_id, span_id ve zaman damgalarını filtreler. data.<key> yalnızca altı dize operatörünü kabul eder (=, !=, contains, not_contains, starts_with, ends_with); backend karşılaştırmaya 400 yanıtı verdiğinden bu filtre çağrıdan önce reddedilir. Uç nokta sıralama ve serbest metin araması desteklemez — sort yok sayılmak yerine reddedilir. read(entity_type="dataset_item", id=…), tablonun kestiği bir değeri geri okumak için gereken tek bir örneğin tamamını döndürür.

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 ile aynı liste artık karşılaştırmayı gösterir — her çalıştırmanın eklendiği örnekleri — ve çalıştırmalara göre filtreler (feedback_scores.<name>, output, duration). Bunlar, iki backend uç noktasındaki farklı alan kümeleridir: schema("list.dataset_item_case") veri kümesinin kendi örnekleridir, schema("list.dataset_item") ise karşılaştırmadır.

Sıralama. trace, span, thread ve experiment, varsayılan olarak sort="<field> [asc|desc]", desc değerlerini alır ve yalnızca bir alan kabul eder: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". Backend sıralayamadığı alanları sessizce yok saydığı için alan, çağrıdan önce varlığın sıralanabilir alanlar listesine göre denetlenir. Çok büyük çalışma alanlarında backend sıralamayı tamamen kaldırır; bu olduğunda başlık bunu belirtir.

dataset_item yalnızca karşılaştırma olarak sıralama yapar (experiment_ids ile): öğeler uç noktası sıralama parametresi almaz; bu nedenle düz bir listelemede sıralama yok sayılmak yerine reddedilir.

Zaman aralığı ve arama. trace, span ve thread, since ile until değerlerini alır; bunların her biri göreli bir süre ("30m", "1h", "7d") veya saat dilimi içeren bir ISO-8601 anı olabilir. Böylece "son bir saat" için saat hesabı yapmanız gerekmez. Aralık, backend için hesaplaması kolay olan ve canlı trafikte start_time ile saniyeler içinde örtüşen kayıt oluşturma zamanına göre belirlenir. Kesin bir sınır için start_time değerini filters içine koyun. Aynı üç tür, kimlik, ad, girdi, çıktı, meta veriler, etiketler ve thread kimliğinin herhangi bir yerinde eşleşen serbest metin olan search değerini de alır. Arama backend'de projenin tamamını tarar; bu nedenle büyük bir projedeki ilk çağrı onlarca saniye sürebilir. Bu çağrılarda 60 saniyelik zaman aşımı uygulanır. since eklemek çağrıları yeniden hızlandırır.

Tabloyu okuma. Süreler duration_ms / ttft_ms olarak etiketlenir ve tam milisaniye cinsinden gösterilir; alan filters ve sort içinde duration olarak kalır. Zaman damgaları saniye hassasiyetinde, maliyetler ise düz ondalık sayılar olarak gösterilir. Proje satırlarında last_updated_trace_at bulunur; böylece hangi projede canlı trafik olduğunu görebilirsiniz. Thread satırlarında ilk mesaj yer alır. Zaman aralığı altında boş bir sayfa, projeye ait son izin ne zaman geldiğini belirtir; varsayılan source = "sdk" altında boş bir sayfa ise diğer kaynakları nasıl görebileceğinizi açıklar. Yanlış yazılmış bir project_name, mevcut en yakın adla yanıtlanır.

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

Diagnostics sorunları. agent_insights_issue, MCP üzerinden Diagnostics sayfasını sunar: Opik'in Diagnostics işi tarafından bir proje için gruplandırılan yinelenen hatalar, arayüzdeki sıralamayla (en son görülen önce) listelenir. Sütunlar severity, status, total_occurrences (tüm zamanların toplamı), latest_count (en son rapor günü; sorunun kendi açıklamasında belirtilen sayı) ve last_seen değerleridir. Varsayılan olarak açık sorunlar listelenir; diğerleri için status="resolved" veya "closed" değerini iletin. read ve list, arayüzün bu sorunlara verdiği ad olan issue ile de yanıtlanır; uzun ad, entity_type enum'unda kullanılan addır. Böylece aynı varlık orada iki kez görünmez. Sayılar arayüzle eşleşmesi için tüm zamanları kapsar; izlerde olduğu gibi aynı since / until zaman aralığını daraltır ve Diagnostics günlük bazda toplama yaptığından aralık UTC rapor günlerine göre kesilir.

Boş bir liste, neden boş olduğunu açıklar; çünkü "hiçbir şey bozuk değil" ile "kimse Diagnostics'i etkinleştirmedi" aksi hâlde aynı görünür. Beş durum vardır: bu dağıtımda Diagnostics kullanılamıyor, bu proje için etkinleştirilmemiş, kapatılmış, etkin ancak yakın zamanda taranmamış ya da etkin ve temiz (son tarama zamanı belirtilir). İşlem yapabileceğiniz durumlarda yapılacak çağrı belirtilir ve her durum projenin Diagnostics sayfasına bağlantı verir.

Boş olmayan bir liste kendi tarih aralığını belirtir. Sorunlar son taramanın gruplandırdığı sorunlardır; bu nedenle yanıt Report covers data through <time> ile biter. İstediğiniz zaman aralığı bu tarihten sonrasına uzanıyorsa, kapsanmayan son bölümü ve bunu nasıl tamamlayacağınızı belirtir: yeniden tarama yeterince geriye ulaştığında bir tetikleyiciyle, aksi hâlde size verilen since ile ham izleri kullanarak. Her gece taranan bir projede bir haftalık veri isterseniz, gruplandırılmış yanıtta son gün eksik kalır; bunu açıklayan da bu bilgidir.

write("agent_insights_job.enable", {"project_name": "demo"}), Diagnostics'i etkinleştirir. Bundan sonra her gün tarama yapılır ve bu çağrıyı yeniden yapmak güvenlidir. write("agent_insights_job.trigger", …), gece taramasını beklemeden son 24 saati hemen tarar. Her ikisi de sorunları okuma iznini gerektirir ve dağıtımda Diagnostics yoksa reddedilir.

Bir sorun, yaşam döngüsü boyunca write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — ele alındı — veya işlem yapmaya değmeyenler için …close ile işaretlenir; …reopen ise her ikisini de yeniden açık listeye alır. Üçü de aynı izni gerektirir ve sorunun taşındığı görünüme bağlantı verir; çünkü çözümlenmiş bir sorun artık varsayılan sayfada yer almaz. Bir hatanın düzeltilip düzeltilmediğine karar vermek yoruma bağlıdır; bu nedenle bunları siz istediğinizde kullanın: asistanın sorunları ayıklarken listeyi kendi başına düzenlemesi doğru değildir.

Zaman içindeki metrikler. project_metric, bir proje için tek bir metriği zaman dilimlerine ayrılmış bir tablo olarak gösterir: iz, span ve thread sayıları; süreler; hata oranları; maliyetler; token kullanımı ve geri bildirim puanları. Genel bakıştan sonra gelen "bir şey ne zaman değişti?" sorusunu yanıtlar.

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

Satırlar kayıtları değil, zaman dilimlerini temsil eder; bu nedenle page, size ve sort yok sayılmak yerine reddedilir. interval, hourly, daily, weekly veya total değeridir; belirtilmezse Metrics sekmesindeki gibi zaman aralığına göre seçilir — 3 güne kadar saatlik, 30 güne kadar günlük, daha uzun sürelerde haftalık. Böylece varsayılan grafik, aralık ne olursa olsun birkaç düzine satırdan oluşur; saatlik bir aylık grafik (721 satır) ise özellikle istenmelidir. since / until, diğer yerlerdekiyle aynı biçimleri alır ve varsayılan olarak son 7 günü kapsar. filters, metriğin ilgili olduğu varlığın alanlarını kullanır; dolayısıyla bir span metriği span alanlarına göre filtrelenir.

breakdown, her zaman dilimini tags, name, error_info, error_type, model, provider, span_type, guardrail_name veya metadata.<key> değerine göre böler. Her metrik bunların tümünü kabul etmez; yedi metrik ise hiçbirini kabul etmez. Araç hangilerinin geçerli olduğunu bilir ve backend'i çağırmadan önce bunu belirtir; aynı soruyu yanıtlayan bir metrik varsa onun adını da verir. Üç aile aynı anda birden fazla seri döndürür (p50/p90/p99 olarak süre, her ad için geri bildirim puanı, her anahtar için token kullanımı). Gruplandırma sırasında backend bunlardan yalnızca birini grafiğe döker; bu nedenle series= bunu seçer: bir yüzdelik dilim, puan adı veya kullanım anahtarı. Süre varsayılan olarak p50, token kullanımı ise total_tokens değerini alır; kullanılan değer ilk satırda belirtilir.

Boş zaman dilimleri atlanır ve altta sayılır; böylece sakin bir ay, sıfırlarla dolu bir sütun yerine birkaç satırdan oluşur. İz içermeyen bir zaman dilimindeki oran da sıfır olarak bildirilmek yerine gösterilmez.

Metrik tablosu, aralıklar ve metrik başına gruplandırma matrisi için schema("list.project_metric") isteyin.

Bir projenin adları. score_name, bir projede kaydedilen geri bildirim puanı adlarını; online_rule ise projede yapılandırılmış otomasyon kuralı değerlendiricilerini listeler. Bu adların çoğu buradan gelir. Her ikisi de read("project", …) tarafından sunulan aynı listelerdir; genel bakıştaki sınırlı sürüm yeterli olmadığında tam ve sayfalandırılmış hâlleri kullanılabilir.

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

`write`

Evrensel yazma yönlendiricisi. operation + data değerlerini iletin; yönlendirici yükü doğrular, uygun REST fiilini uygular ve backend yanıtını döndürür.

İşlemler:

İşlem	Ne yapar
`trace.create`	Tek bir iz (veya bir toplu işlem) kaydeder. Span'ler / puanlar / yorumlar için üst kayıttır.
`trace.update`	Mevcut bir izi tamamlar veya değiştirir.
`span.create`	Mevcut bir ize span kaydeder (veya toplu olarak kaydeder).
`score.create`	Bir iz, span veya thread'e sayısal geri bildirim puanı ekler.
`comment.create`	Bir iz, span veya thread'e serbest metinli yorum ekler.
`prompt_version.save`	Yeni bir prompt sürümü kaydeder (yoksa ada göre prompt oluşturur).
`dataset.create`	Veri kümesi oluşturur — `type: "test_suite"` bunu değerlendirme test paketine dönüştürür.
`dataset_item.upsert`	Veri kümesine öğe ekler veya mevcut öğeleri günceller (her zaman zarf biçiminde).
`experiment.create`	Bir veri kümesine bağlı deney oluşturur.
`experiment_item.create`	Deneye iz + dataset_item satırları ekler.
`thread.close`	Thread'i kapatır (etkin değil olarak işaretler). `thread_id` ve projeyi iletin.
`thread.open`	Kapatılmış bir thread'i yeniden açar. `thread_id` ve projeyi iletin.
`agent_insights_job.enable`	Bir proje için Diagnostics'i etkinleştirir (günlük taramalar; tekrarlanması güvenlidir).
`agent_insights_job.trigger`	Son 24 saati kapsayan bir Diagnostics taramasını hemen çalıştırır.
`agent_insights_issue.resolve`	Bir Diagnostics sorununu ele alındı olarak işaretler (önce kullanıcıya sorun).
`agent_insights_issue.close`	Bir Diagnostics sorununu işlem yapmaya değmez olarak işaretler (önce kullanıcıya sorun).
`agent_insights_issue.reopen`	Çözümlenmiş veya kapatılmış bir Diagnostics sorununu yeniden açık listeye alır.
`annotation_queue.create`	İsteğe bağlı olarak özel bir açıklama ekleyici görünümüyle proje için açıklama kuyruğu oluşturur.
`annotation_queue.update`	Açıklama kuyruğunu değiştirir; açıklama ekleyici görünümünü ayarlar, değiştirir veya temizler.

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

`schema`

Herhangi bir yazma işlemini çağırmadan önce tam JSON biçimini ve gerekli alanları inceleyin — data değerinin nasıl görünmesi gerektiğinden emin olmadığınızda kullanışlıdır. Şemayı, OAuth kapsamını ve doğrulanmış bir örneği döndürür. Yalnızca bilgi arar; backend çağrısı yapmaz.

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

Aynı araç, list.trace, list.span, list.thread ve list.experiment için, ilgili varlığın list aracındaki referansını yanıt olarak verir: türü ve geçerli işleçleriyle filtrelenebilir her alan, sıralanabilir alanlar, zaman aralığı ve serbest metin aramasının geçerli olup olmadığı ve iki örnek filtre.

schema(operation="list.trace")

Yapılandırma

Bunlar yerel sunucuyu yapılandırır; her ayar bir ortam değişkenidir. Opik Cloud'daki barındırılan sunucu bunların hiçbirini almaz.

Kimlik / uç nokta

Değişken	Varsayılan	Notlar
`OPIK_API_KEY`	—	Kendi barındırdığınız Comet için veya barındırılan sunucu olmadan Opik Cloud için API anahtarı. Açık kaynak Opik, dağıtım kimlik doğrulaması eklemediği sürece anahtar gerektirmez.
`OPIK_WORKSPACE`	unset	Çalışma alanı adı. API anahtarıyla bulutta ayarlanmazsa `default` gönderilir ve bu, hesabınızın varsayılan çalışma alanına karşılık gelir — farklı bir çalışma alanında çalışıyorsanız bunu açıkça ayarlayın; aksi takdirde okumalar sessizce yanlış çalışma alanından yapılır. OAuth kullanırken (belirteç bunu taşır) ve yerel/OSS ortamında ayarlamayın (`default` oradaki tek çalışma alanıdır).
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` için kullanımdan kaldırılmış takma ad (geriye dönük uyumluluk). İkisi de ayarlanmışsa `OPIK_WORKSPACE` önceliklidir.
`COMET_WORKSPACE_ID`	unset	İsteğe bağlı çalışma alanı UUID'si. Ayarlandığında analiz etkinliklerine eklenir ve çözümlenen değere öncelik tanır. Nadiren gerekir — OAuth kurulumları UUID'yi belirteçten otomatik olarak alır.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Kendi barındırdığınız Comet ana makinenize veya hazırlık ortamı için `https://dev.comet.com` değerine ayarlayın.
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api` değerlerinden türetilir	API'sini `/api` adresinde sunan açık kaynak Opik için ayarlayın (yerel ortamda `http://localhost:5173/api`). Comet platformunda, yalnızca Opik Comet kullanıcı arayüzünden farklı bir ana makinede/yolda bulunuyorsa geçersiz kılın.
`OPIK_DEFAULT_PROJECT_NAME`	unset	Ayarlandığında, oturum başına `instructions` blob'u LLM'ye, kullanıcı farklı bir proje belirtmediği sürece her araç çağrısında bunu `project_name` olarak iletmesini söyler.

Sunucu / aktarım

Değişken	Varsayılan	Notlar
`OPIK_MCP_TRANSPORT`	`stdio`	Ana makine tarafından başlatıldığında `stdio`, bir bağlantı noktasında dinlemek için `streamable-http`.
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn bağlama ana makinesi (yalnızca `streamable-http`).
`OPIK_MCP_PORT`	`8080`	uvicorn bağlama bağlantı noktası (yalnızca `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload` özelliğini etkinleştirmek için `true` (yalnızca geliştirme).
`OPIK_MCP_AS_URL`	unset	`/.well-known/oauth-protected-resource` (RFC 9728) içinde duyurulan ve AS keşif sorguları için proxy hedefi olarak kullanılan OAuth Yetkilendirme Sunucusu URL'si. MCP ana makinelerinin HTTP üzerinden OAuth akışını başlatması için gereklidir.
`OPIK_MCP_RESOURCE_URI`	unset	Bu sunucunun korumalı kaynak meta verilerinde `resource` olarak duyurulan ve `WWW-Authenticate` ipucunu türetmek için kullanılan standart genel URI'si.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	opik-backend'in belirteç iç gözleminden aldığı "geçerli" yanıtın, aynı OAuth belirteciyle yapılan sonraki istekte yeniden sorgulanmadan önce ne kadar süre güvenilir sayılacağını belirler. İstek başına doğrulamanın arka uca eklediği yükü ve süresi dolmuş bir belirtecin iletilmeye devam ettiği süreyi sınırlar (bu süre, arka ucun döndürdüğü ilk 401 yanıtında da sona erer). Arka uç bildirdiğinde, belirtecin kendi `expires_at` değeriyle sınırlandırılır.
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr günlük kaydı eşiği.

Aktarım seçimi

İki bearer biçimi, HTTP aktarımında iki farklı sözleşme. Bir opik_mcp_at_… OAuth erişim belirteci, opik-backend'in belirteç iç gözlem uç noktasına karşı her istekte doğrulanır önbelleğe alınır, bkz. OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S; süresi dolmuş veya iptal edilmiş bir belirteç, MCP ana makinelerinin sessiz refresh_token yetkilendirmesini başlatmak için kullandığı WWW-Authenticate: Bearer error="invalid_token" içeren bir HTTP 401 yanıtı alır. Opik API anahtarı yerel olarak doğrulanmaz: opik-backend'e olduğu gibi iletilir ve tek yaptırım noktası burasıdır. Aktarımı dağıtım biçimine göre seçin:

Senaryo	Aktarım
Opik Cloud	Çalıştırılacak bir şey yok: barındırılan sunucu, Comet tarafından çalıştırılan bu sunucunun HTTP üzerinden sunulan hâlidir
MCP istemcisi ve Opik aynı makinede (yerel OSS kurulumu)	stdio (önerilir — en basit seçenek; bağlantı noktası ve OAuth kurulumu gerekmez)
Yerel MCP istemcisi → kendi barındırdığınız Opik	Dağıtımın ortam değişkenleriyle stdio veya OAuth ile HTTP (`OPIK_MCP_AS_URL` arka ucu gösterir)
opik-mcp, opik-backend ile aynı uç noktanın arkasında sunuluyor	HTTP — bearer belirteçleri her istekte arka uç tarafından doğrulanır

Yerel OSS kurulumları için not: OSS arka ucu isteklerin kimliğini doğrulamaz; bu nedenle önündeki bir HTTP opik-mcp, OSS REST API'sinin kendisi kadar açıktır. Paylaşılan ağlarda varsayılan 127.0.0.1 bağlama ayarını koruyun (ve stdio'yu tercih edin).

Telemetri

Değişken	Varsayılan	Notlar
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Sentry dışındaki tüm telemetriyi devre dışı bırakmak için `false` olarak ayarlayın.
`OPIK_MCP_SENTRY_ENABLED	`true`	Set to `false`
=======

Bilinen ana makine sınırları

Ana makinelerin tek bir araç çağrısının çalışmasına izin verdiği süre değişir:

Claude Code — belgelenmiş bir araç çağrısı zaman aşımı yok. Önerilir.
Cursor — ilerleme kaydedilse bile sıfırlanmayan, kesin 60 saniyelik zaman aşımı (yukarı akış hatası).
MCP Inspector — toplam süreyi MAX_TOTAL_TIMEOUT ile sınırlar (varsayılan 60 saniye). Uzun işlemler için Inspector kullanıcı arayüzünde bu değeri artırın.

Bir çağrı takılırsa tam istek günlüğü için OPIK_MCP_LOG_LEVEL=DEBUG ayarlayın.

Sorun giderme

Kurulum çalışıyor mu? Sunucuyu istemci yapılandırmasındaki ortam değişkenleriyle ve --check ile çalıştırın: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Çalışma alanını ve gördüğü projeleri listeler veya neyin düzeltilmesi gerektiğini söyler. Sunucunun kendi hataları da neyi değiştirmeniz gerektiğini belirtir ve ilgili belgeler sayfasına bağlantı verir.

OPIK_API_KEY algılanmıyor — değişken sunucu işlemine ulaşmıyor. Claude Code / Cursor / VS Code'da ortam değişkenleri kabuğunuzda değil, yalnızca MCP sunucu yapılandırmasının env bloğunda geçerlidir; Codex de yalnızca env_vars içinde listelenen adları iletir. Düzenleme yaptıktan sonra yeni bir oturum başlatın; istemciler yapılandırmayı oturum başlarken okur.

Açık kaynak Opik'te istekler /opik/api adresine gidiyor — COMET_URL_OVERRIDE, kendi barındırdığınız Comet platformu içindir. Açık kaynak sürüm API'sini /api adresinde sunar: bunun yerine OPIK_URL=http://localhost:5173/api (veya https://<host>/api) ayarlayın. Ana makine bu makine olduğunda sunucu başlangıçta bu konuda uyarı verir ve --check "No Opik API at …" yanıtını verir.

Cursor çağrısı 60 saniyede zaman aşımına uğruyor — bu, opik-mcp kaynaklı değil, Cursor'ın bilinen bir hatasıdır. Çağrıyı daraltın (daha küçük size, daha kısa bir zaman aralığı) veya aynı işlemi kesin bir sınırı olmayan Claude Code'da çalıştırın.

Sunucu görünmüyor, oturum açma açılmıyor, yanlış çalışma alanı, uvx bulunamadı. Bunlar belgelerin sorun giderme bölümünde ele alınmıştır. uvx opik@latest mcp status, sunucunun yapılandırıldığı tüm istemcileri ve yapılandırmalarının güncel olup olmadığını listeler.

Geliştirme

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

Yaygın hedefler:

Hedef	Ne yapar
`make install`	`uv sync --locked --extra dev`
`make run`	MCP sunucusunu çalıştırır (varsayılan olarak stdio).
`make run-dev`	DEBUG günlük kaydı + uvicorn `--reload` ile çalıştırır.
`make dev`	`mcp dev` üzerinden çalıştırır (Inspector geliştirme modu sarmalayıcısı).
`make inspect`	MCP Inspector'ı çalışan bir sunucuya bağlayarak başlatır.
`make test`	`uv run pytest -q`.
`make lint`	`ruff check` + biçim denetimi.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Depo düzeni:

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

Yardım alın

Hatalar ve özellik istekleri için sorun bildirin
SDK / arka uç belgeleri için Opik belgeleri
Sorularınız için Comet topluluk Slack'i

Lisans

Apache-2.0.

Comet Opik

Comet Opik MCP ile neler yapabilirsiniz?

Dokümantasyon

Opik MCP Sunucusu

Hızlı başlangıç

Opik Cloud: barındırılan sunucu

Claude Code eklentisi

Kendi sunucunuzda barındırılan ve açık kaynaklı Opik: yerel sunucu

Kodlama aracısıyla yükleme

Elle kurulum (Opik kontrolü yok, beceri paketi yok)

Barındırılan sunucu (Opik Cloud)

Claude Code, elle

Codex, elle

Cursor, elle

VS Code Copilot, elle

Diğer istemciler

API anahtarıyla Opik Cloud

Yerel sunucu (kendi barındırdığınız ve açık kaynaklı Opik)

Claude Code, elle

Codex, elle

Cursor, elle

VS Code Copilot, elle

MCP Inspector (elle test)

npx opik-mcp kullanıyorsanız

Araçlar

read

list

write

schema

Yapılandırma

Kimlik / uç nokta

Sunucu / aktarım

Aktarım seçimi

Telemetri

Bilinen ana makine sınırları

Sorun giderme

Geliştirme

Yardım alın

Lisans

`npx opik-mcp` kullanıyorsanız

`read`

`list`

`write`

`schema`