Comet Opik MCP Server

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

211

Dokümantasyon

opik-mcp

Eski npx opik-mcp'den mi geçiş yapıyorsunuz? TypeScript sunucusu kullanımdan kaldırıldı ve 2026-11-15 tarihinde sona eriyor. MCP istemci yapılandırmanızda npx -y opik-mcp yerine uvx opik-mcp@latest kullanın. Tam kılavuz: legacy/typescript/MIGRATION.md.

Opik + Ollie için Model Bağlam Protokolü sunucusu. Yapay zeka sunucunuzu (Claude Code, Cursor, VS Code Copilot, MCP Inspector) doğrudan Opik çalışma alanınıza bağlayın — izleri okuyun, puanları kaydedin, istem sürümlerini kaydedin ve Ollie'ye araştırma soruları sorun, hepsini sohbet üzerinden yapın.

Halihazırda Opik kullanan ve onu kod yazdıkları yapay zeka asistanından yönetmek isteyen LLM mühendisleri için tasarlanmıştır.

You:    "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…"

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

Kurulum

opik-mcp bir Python paketidir (Python 3.13+ gerektirir). Çalıştırmanın önerilen yolu uvx kullanmaktır; bu, talep üzerine yayınlanmış en son sürümü getirir ve çalıştırır — genel kurulum yok, virtualenv hokkabazlığı yok.

uv bir kez kurun:

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

Opik çalışma alanınızdan iki şeye ihtiyacınız olacak:

OPIK_API_KEY — comet.com/api/my/settings/ adresinden alın.
OPIK_WORKSPACE — çalışma alanı adınız (URL'de göründüğü gibi küçük harf). Örn. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. İsteğe bağlı — varsayılan default (Opik SDK kuralı), yerel/OSS kurulumları için doğrudur; adlandırılmış bir çalışma alanına sahip bulut kullanıcıları bunu ayarlamalıdır. COMET_WORKSPACE, kullanımdan kaldırılmış bir takma ad olarak kabul edilir.

Ön sürüm notu: opik-mcp (Python) henüz PyPI'de yayınlanmadı. İlk PyPI sürümü yayınlanana kadar, aşağıdaki herhangi bir kod parçacığında uvx opik-mcp yerine şunu kullanın: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE isteğe bağlıdır. Aşağıdaki herhangi bir kod parçacığında OPIK_WORKSPACE satırını/anahtarını atlayın; sunucu default çalışma alanını kullanır (yerel/OSS kurulumları için doğrudur). Yalnızca adlandırılmış bir bulut çalışma alanına bağlanıyorsanız ayarlayın.

Claude Code

Sunucuyu tek bir komutla ekleyin:

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

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

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

Claude Code'u yeniden başlatın. /mcp ile doğrulayın — opik-mcp bağlı olarak görünmelidir. Ardından sohbette şunu sorun: "Opik projelerimi listele" — Claude, list aracını çağıracak ve çalışma alanınızdaki projeleri göreceksiniz.

Cursor

~/.cursor/mcp.json (genel) veya .cursor/mcp.json (proje) dosyasını düzenleyin veya Cmd+Shift+J → Özellikler → Model Bağlam Protokolü'nü açın:

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

Cursor'ı yeniden yükleyin; MCP panelinde opik-mcp yanındaki yeşil nokta bağlantıyı onaylar. Sohbette şunu sorun: "Opik projelerimi listele".

Cursor 60s zaman aşımı. Cursor, ilerleme bildirimlerinde sıfırlanmayan katı bir araç çağrısı zaman aşımı uygular. Uzun ask_ollie dönüşleri Cursor'da başarısız olur. Bkz. Bilinen ana bilgisayar sınırları.

VS Code Copilot

Çalışma alanınızda (veya Kullanıcı Ayarları JSON'unda) .vscode/mcp.json:

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

Pencereyi yeniden yükleyin; sunucuya erişilebilir olduğunda Copilot Chat MCP göstergesi opik-mcp'yi gösterir. Sohbette şunu sorun: "Opik projelerimi listele".

MCP Inspector (manuel test)

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

Kendi kendine barındırılan Opik

Ana bilgisayar yapılandırmanızdaki aynı env bloğuna COMET_URL_OVERRIDE (ve Opik varsayılan olmayan bir yolda bulunuyorsa OPIK_URL) ekleyin:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

ask_ollie ve run_experiment yalnızca Comet Cloud'da kullanılabilir — kendi kendine barındırılanlarda bu çağrılar gönderimde başarısız olur, bu nedenle doğrudan read / list / write kullanın. OPIK_MCP_ANALYTICS_SOURCE="" ayarı, kurulumunuzu telemetri olaylarındaki bulut-Comet kaynak etiketinden çıkarır.

Araçlar

opik-mcp, sonuç odaklı küçük bir yüzey sunar — tam yaşam döngüsünü (oku → açıklama ekle → düzenle → yaz → yinele) kapsayan altı araç.

Araç	Amaç
`read`	Kimlik / ad / `opik://` URI'sine göre evrensel okuma
`list`	İsteğe bağlı ad filtresi + sayfalandırma ile evrensel listeleme
`ask_ollie`	Opik ürün içi asistanı aracılığıyla araştırma / sentezleme
`write`	Evrensel yazma — izleri/açıklıkları günlüğe kaydetme, puanlama, yorum yapma, istemleri kaydetme, test paketlerini ve deneyleri yönetme
`schema`	Yazma işlemi şemalarını inceleme (LLM tarafından geçerli yükler oluşturmak için kullanılır)
`run_experiment`	Ollie aracılığıyla uçtan uca bir değerlendirme deneyi çalıştırma

`read`

Herhangi bir "bana X'i göster" sorusu için tek bir araç. Bir entity_type artı bir id (UUID veya adlandırılabilir türler için bir ad) veya tam bir opik:// URI'si alır. Bileşik okumalar (trace, prompt) alt öğelerini satır içine alır, böylece tek bir çağrı tam resmi döndürür.

Desteklenen varlıklar: project, trace, span, test_suite, experiment, prompt. Ada dayalı arama project, experiment, prompt, test_suite için kullanılabilir (daha yavaş — iki API çağrısı — ve birden çok eşleşme döndürebilir).

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

`list`

İsteğe bağlı ad filtresi ve sayfalandırma ile bir koleksiyona göz atın. Proje kapsamlı türler (trace, test_suite_item, prompt_version) üst öğelerinin UUID'sini gerektirir.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

Araştırma soruları, varlıklar arası sentez veya Opik alan uzmanlığı gerektiren her şey için. Ollie, çalışma alanınıza doğrudan okuma erişimine sahiptir ve istendiğinde akış ortasında yazma işlemleri (puanlar, yorumlar, test paketi öğeleri, istem sürümleri) gerçekleştirebilir.

ask_ollie(query="Why are spans in project 'demo' slower this week than last?")
ask_ollie(query="Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.")

Asistanın son metnini artı bir thread_id döndürür. Bağlamı korumak için takip eden sorularda bunu geri iletin — Ollie'nin iş parçacıkları arasında belleği yoktur.

YOLO modu (varsayılan). Ollie'nin akış ortasında gerçekleştirdiği yazma işlemleri, eylem başına onay olmadan yürütülür. Her otomatik onay, opik_mcp.audit Python kaydedicisinde bir JSON denetim satırı olarak günlüğe kaydedilir. Bunun yerine onay gerektirmek için OPIK_MCP_AUTO_APPROVE=disabled ayarlayın — Ollie'nin onay istekleri daha sonra manuel olarak yeniden yayınlayabileceğiniz yazılı hatalar olarak ortaya çıkar.

Yalnızca Comet Cloud'da kullanılabilir.

`write`

Evrensel yazma dağıtıcısı. operation + data iletin; dağıtıcı yükü doğrular, doğru REST fiilini uygular ve arka uç yanıtını döndürür.

İşlemler:

İşlem	Ne yapar
`trace.create`	Tek bir izi (veya bir toplu işi) günlüğe kaydeder. Açıklıklar / puanlar / yorumlar için üst öğe.
`trace.update`	Mevcut bir izi sonlandırır veya değiştirir.
`span.create`	Mevcut bir iz üzerinde bir açıklığı (veya bir toplu işi) günlüğe kaydeder.
`score.create`	Bir ize, açıklığa veya iş parçacığına sayısal bir geri bildirim puanı ekler.
`comment.create`	Bir ize, açıklığa veya iş parçacığına serbest metin yorumu ekler.
`prompt_version.save`	Yeni bir istem sürümü kaydeder (yoksa ada göre istemi oluşturur).
`test_suite.create`	Bir değerlendirme test paketi oluşturur.
`test_suite_item.upsert`	Bir test paketine öğeleri yükseltir (her zaman zarf şeklinde).
`experiment.create`	Bir test paketine kapsamlı bir deney oluşturur.
`experiment_item.create`	Bir deneye iz + dataset_item satırları ekler.

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

`schema`

Çağırmadan önce herhangi bir yazma işleminin tam JSON şeklini ve gerekli alanlarını inceleyin — data'in 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. Salt arama, arka uç çağrısı yok.

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

`run_experiment`

Ollie aracılığıyla uçtan uca bir değerlendirme deneyi çalıştırın. Opik'in deney şeklini (istem, test paketi, puanlayıcılar) yansıtan tek bir experiment_config sözlüğü alır; Ollie çalıştırmayı yürütür ve sonuçları bir Opik deneyi olarak geri yazar.

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

Yalnızca Comet Cloud'da kullanılabilir.

Yapılandırma

Her ayar bir ortam değişkenidir. Gerekli olanlar kalın olarak belirtilmiştir.

Kimlik / uç nokta

Değişken	Varsayılan	Notlar
`OPIK_API_KEY`	—	`ask_ollie` ve herhangi bir kimlik doğrulamalı okuma/yazma için gereklidir.
`OPIK_WORKSPACE`	`default`	Çalışma alanı adı. İsteğe bağlı — `default` (Opik SDK kuralı) olarak geri döner. Adlandırılmış bir çalışma alanına sahip bulut kullanıcıları bunu ayarlamalıdır.
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` için kullanımdan kaldırılmış takma ad (geriye dönük uyumluluk). Her ikisi de ayarlanmışsa `OPIK_WORKSPACE` kazanır.
`COMET_WORKSPACE_ID`	—	İsteğe bağlı çalışma alanı UUID'si. Ayarlandığında, BI'ın (değişebilir) çalışma alanı adı yerine sabit bir kimlik üzerinde birleştirme yapabilmesi için analitik olaylarına damgalanır.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Kendi kendine barındırılan Comet ana bilgisayarınıza veya hazırlık için `https://dev.comet.com` olarak ayarlayın.
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api`'den türetilir	Yalnızca Opik, Comet UI'sinden farklı bir ana bilgisayarda/yolda bulunuyorsa geçersiz kılın.
`OPIK_DEFAULT_PROJECT_NAME`	ayarlanmamış	Ayarlandığında, oturum başına `instructions` blobu, LLM'ye, kullanıcı farklı bir proje adlandırmadığı sürece bunu her araç çağrısında `project_name` olarak iletmesini söyler.

Sunucu / aktarım

Değişken	Varsayılan	Notlar
`OPIK_MCP_TRANSPORT`	`stdio`	Ana bilgisayar tarafından başlatılan için `stdio`, bir bağlantı noktasını dinlemek için `streamable-http`.
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn bağlama ana bilgisayarı (yalnızca `streamable-http`).
`OPIK_MCP_PORT`	`8080`	uvicorn bağlama bağlantı noktası (yalnızca `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload`'yi etkinleştirmek için `true` (yalnızca geliştirme).
`OPIK_MCP_AS_URL`	ayarlanmamış	`/.well-known/oauth-protected-resource`'te (RFC 9728) tanıtılan ve AS keşif araştırmaları için proxy hedefi olarak kullanılan OAuth Yetkilendirme Sunucusu URL'si. MCP ana bilgisayarlarının HTTP üzerinden OAuth dansını başlatması için gereklidir.
`OPIK_MCP_RESOURCE_URI`	ayarlanmamış	Bu sunucunun kurallı genel URI'si, korunan kaynak meta verilerinde `resource` olarak tanıtılır ve `WWW-Authenticate` ipucunu türetmek için kullanılır.
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr kaydedici eşiği.

Aktarım seçimi

opik-mcp, HTTP aktarımında yerel kimlik bilgisi doğrulaması yapmaz: iyi biçimlendirilmiş herhangi bir Authorization: Bearer … (bir Opik API anahtarı veya bir opik_mcp_at_… OAuth erişim belirteci), tek yetkilendirme uygulama noktası olan opik-backend'e değiştirilmeden iletilir. Aktarımı dağıtım şekline göre seçin:

Senaryo	Aktarım
MCP istemcisi ve Opik aynı makinede (yerel OSS kurulumu)	stdio (önerilir — en basiti, bağlantı noktası yok, OAuth kurulumu yok)
Yerel MCP istemcisi → uzak Opik (Comet bulutu / kendi kendine barındırılan)	`OPIK_API_KEY` ile stdio veya OAuth ile HTTP (`OPIK_MCP_AS_URL` arka ucu işaret eder)
opik-backend ile aynı kenarın arkasında barındırılan opik-mcp	HTTP — taşıyıcılar istek başına arka uç tarafından doğrulanır

Yerel OSS kurulumları için not: OSS arka ucu istekleri 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ğlamasını koruyun (ve stdio'yu tercih edin).

Ollie / uzun çağrılar

Değişken	Varsayılan	Notlar
`OPIK_MCP_AUTO_APPROVE`	`enabled`	Ollie'nin akış ortası yazma işlemleri devam etmeden önce eylem başına onay gerektirmesi için `disabled`. MCP `elicitation` yeteneğini tanıtan ana bilgisayarlarda kullanıcı bir evet/hayır istemi görür; daha basit ana bilgisayarlarda istek, manuel olarak yeniden yayınlayabileceğiniz yazılı bir hata olarak ortaya çıkar.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie'nin akış ortası onay isteminin, iptal olarak değerlendirilmeden önce kullanıcıyı ne kadar bekleyebileceği. `0` sınırı devre dışı bırakır (yalnızca hata ayıklama).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie pod'u soğuk başlatma yoklama üst sınırı.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Soğuk başlatma yoklama aralığı.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Gözetim ritmi — pod sessiz olduğunda bir `notifications/progress` işareti yayar, ana bilgisayar zaman aşımlarını uzak tutar.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	`ask_ollie` iptal etmeden önce pod sessizliği için katı üst sınır. `0` devre dışı bırakır (yalnızca hata ayıklama).

Telemetri

Anonim kullanım olayları (yalnızca olay türü + zamanlama — sorgu içeriği yok). Destek ekibinin hesabınızı bulabilmesi için API anahtarınızın bir SHA-256 özeti dahil edilir; ham anahtar işlemden asla çıkmaz. Devre dışı bırakma: OPIK_MCP_ANALYTICS_ENABLED=false.

Değişken	Varsayılan	Notlar
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Tüm telemetriyi devre dışı bırakmak için `false` olarak ayarlayın.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Staging için geçersiz kılma.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Her olaya etiket (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Alıcı bunu `on_prem=False` işaretlemek için kullanır. Şirket içi kurulumlar `""` veya kendi alan adlarıyla geçersiz kılmalıdır.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP bağlantı zaman aşımı.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP toplam istek zaman aşımı.

Bilinen ana bilgisayar sınırları

MCP şartnamesi, ana bilgisayarların araç çağrısı zaman aşımını notifications/progress üzerinde sıfırlamasına izin verir — opik-mcp her Ollie SSE olayı için bir tane artı 15 saniyelik bir gözlemci kalp atışı yayar. Gerçeklik tutarsızdır:

Claude Code — belgelenmiş araç çağrısı zaman aşımı yoktur; kalp atışı, message_end kadar çağrıyı canlı tutar. Önerilir.
Cursor — ilerlemede sıfırlanmayan (sıfırlanmaz) sabit 60 saniyelik zaman aşımı (yukarı akış hatası). Uzun Ollie dönüşleri başarısız olur. ask_ollie sorgularını odaklı tutun.
MCP Inspector — MAX_TOTAL_TIMEOUT toplam süreyi sınırlar (varsayılan 60s). Uzun işlemler için Inspector kullanıcı arayüzünde artırın.

Bir çağrı takılırsa, OPIK_MCP_LOG_LEVEL=DEBUG ayarlayın — kalp atışı hataları (genellikle ana bilgisayar bağlantı kopmaları) opik_mcp.ask_ollie üzerinde hata ayıklama seviyesinde günlüğe kaydedilir.

Sorun Giderme

OPIK_API_KEY is required to use ask_ollie — değişken sunucu sürecine ulaşmıyor. Claude Code / Cursor / VS Code'da, ortam değişkenleri yalnızca MCP sunucu yapılandırmasının env bloğu içindeyken uygulanır, kabuğunuzda değil. Düzenledikten sonra ana bilgisayarı yeniden başlatın.

ask_ollie 2 dakika sonra "pod hazır değil" döndürüyor — Ollie pod'unun soğuk başlatması OPIK_MCP_POD_READY_TIMEOUT_S aştı. Yeniden deneyin — ikinci çağrı genellikle sıcak bir pod'a ulaşır.

ask_ollie / run_experiment şirket içinde barındırılan Opik'te bir dağıtım hatasıyla başarısız oluyor — bu araçlar yalnızca Comet Cloud'da kullanılabilir. Şirket içinde barındırılanda doğrudan read / list / write kullanın.

Cursor çağrısı 60 saniyede zaman aşımına uğruyor — Cursor'un bilinen hatası, opik-mcp değil. Ollie sorgusunu kısaltın veya aynı işlemi sabit bir üst sınırı olmayan Claude Code'da çalıştırın.

Geliştirme

git clone [email protected]:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

Yaygın hedefler:

Hedef	Ne yapar
`make install`	`uv sync --extra dev`
`make run`	MCP sunucusunu çalıştır (varsayılan olarak stdio).
`make run-dev`	DEBUG günlükleme + uvicorn `--reload` ile çalıştır.
`make dev`	`mcp dev` aracılığıyla çalıştır (Inspector geliştirme modu sarmalayıcısı).
`make inspect`	Çalışan bir sunucuya karşı MCP Inspector'ı başlat.
`make test`	`uv run pytest -q`.
`make test-live`	`dev.comet.com` karşı canlı uçtan uca (`OPIK_API_KEY` + `OPIK_WORKSPACE` ayarlayın).
`make lint`	`ruff check` + biçim kontrolü.
`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, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

Yardım alın

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

v2'den yükseltme mi yapıyorsunuz? Eski TypeScript sunucusu hala npm'de opik-mcp@^2 (npx -y opik-mcp) olarak yayınlanır; kaynak legacy/typescript/ altında korunur. Destek politikası için legacy/typescript/DEPRECATED.md sayfasına bakın.

Lisans

Apache-2.0.