Comet Opik

Opik MCP Sunucusu

Opik için resmi Model Context Protocol (MCP) sunucusu — Comet tarafından geliştirilen açık kaynaklı LLM gözlemlenebilirlik ve değerlendirme platformu Opik.
AI ana bilgisayarınızı (Claude Code, Cursor, VS Code Copilot, MCP Inspector) doğrudan
Opik çalışma alanınıza bağlayın: izleri okuyun, puanları kaydedin, prompt sürümlerini saklayın ve
Opik'in ürün içi AI asistanı Ollie'ye araştırma soruları sorun — hepsi
sohbetten.

Opik'i zaten çalıştıran ve kod yazarken kullandıkları AI asistanından yönetmek isteyen
LLM mühendisleri için geliştirilmiştir.

Eski npx opik-mcp sürümünden mi geçiyorsunuz? TypeScript sunucusu kullanımdan kaldırıldı
ve 2026-11-15 tarihinde kullanımdan kaldırılacak. MCP istemci yapılandırmanızda
npx -y opik-mcp yerine uvx opik-mcp@latest kullanın. Tam rehber: legacy/typescript/MIGRATION.md.

You: "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…" You: "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

Kurulum

opik-mcp bir Python paketidir (Python 3.13+ gerektirir). Çalıştırmanın önerilen yolu
uvx kullanmaktır; bu, en son yayınlanan sürümü isteğe bağlı olarak getirir ve çalıştırır —
global kurulum veya sanal ortam yönetimi gerekmez.

uv öğesini 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 (küçük harf, URL'de göründüğü gibi). Örn. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. COMET_WORKSPACE kullanımdan kaldırılmış bir takma ad olarak kabul edilir.

API anahtarıyla bulut: hesap varsayılanınız istediğiniz değilse ayarlayın.
Boş bırakılırsa, sunucu default gönderir; Comet bunu hesabınızın
varsayılan çalışma alanına çözer. Bu çalışır, ancak gerçekten adlandırılmış bir
çalışma alanında çalışıyorsanız, size hiçbir şey söylemeden farklı bir alana
yönlendirilirsiniz — okumalarınız hata vermek yerine yanlış yerden gelir.

OAuth ile bulut: boş bırakın. Çalışma alanı yetki verdiğiniz belirteçten gelir
ve sunucu bu ayarı tamamen yok sayar.

Yerel / açık kaynak: boş bırakın. Açık kaynak Opik'in default adında
tek bir çalışma alanı vardır ve başka oluşturmanın yolu yoktur; bu tam olarak
varsayılanın size verdiği şeydir.

Kendi kendine barındırılan Comet: ayarlayın. Açık kaynaktan farklı olarak, bu dağıtımlarda
gerçek adlandırılmış çalışma alanları vardır ve aynı sessiz yanlış çalışma alanı riski geçerlidir.

Hangisi geçerli olursa olsun, değerin gerçekten değiştirildiğinden emin olun.
Yaygın kullanılan kod parçacıkları <your-workspace> veya ${input:OPIK_WORKSPACE} gibi yer tutucular içerir;
olduğu gibi yapıştırılırsa, bunlar çalışma alanı adı değildir. Sunucu artık bunları
hiçbir şey açıklamayan bir kimlik doğrulama hatasıyla yanıt vermek yerine doğrudan reddeder.

Claude Code

Sunucuyu tek komutla ekleyin:

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

Veya ~/.claude.json dosyasını doğrudan 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ızın projelerini göreceksiniz.

Cursor

~/.cursor/mcp.json (genel) veya .cursor/mcp.json (proje) dosyasını düzenleyin veya
Cmd+Shift+J → Özellikler → Model Context Protocol bölümünü açın:

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

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

Cursor 60 saniye zaman aşımı. Cursor, ilerleme bildirimlerinde sıfırlanmayan
sabit bir araç çağrısı zaman aşımı uygular. Uzun ask_ollie turları Cursor'da başarısız olur.
Bkz. Bilinen ana bilgisayar sınırlamaları.

VS Code Copilot

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

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

Pencereyi yeniden yükleyin; Copilot Sohbet MCP göstergesi, sunucuya ulaşıldığında
opik-mcp 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 yaşıyorsa OPIK_URL) ekleyin:

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

Açık kaynaklı bir dağıtımda OPIK_WORKSPACE atlayın; burada default tek
çalışma alanıdır; gerçek adlandırılmış çalışma alanlarına sahip kendi kendine barındırılan
Comet'te saklayın.

ask_ollie ve run_experiment yalnızca Comet Cloud'da kullanılabilir —
kendi kendine barındırılan sürümlerde 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 küçük, sonuç odaklı bir yüzey sunar — tam yaşam döngüsünü kapsayan altı araç
(okuma → açıklama → düzenleme → yazma → yineleme).

read

Herhangi bir "bana X'i göster" sorusu için tek araç. Bir entity_type artı bir id
(UUID veya adlandırılabilir türler için bir ad) veya tam bir opik:// URI 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 göre 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 sayfalama ile bir koleksiyona göz atın. Proje kapsamlı
türler (trace, test_suite_item, prompt_version) üst UUID'lerini 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'nin çalışma alanınıza doğrudan okuma erişimi vardır ve
istendiğinde akış sırasında yazma işlemleri (puanlar, yorumlar, test paketi öğeleri, prompt 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 sorularında geri iletin — Ollie'nin iş parçacıkları arasında hafızası yoktur.

YOLO modu (varsayılan). Ollie'nin akış sırası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
logger'ında bir JSON denetim satırı olarak kaydedilir. Bunun yerine onay gerektirmek için
OPIK_MCP_AUTO_APPROVE=disabled ayarlayın — Ollie'nin onay istekleri daha sonra
manuel olarak yeniden gönderebileceğiniz yazılı hatalar olarak görünür.

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:

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 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. Saf 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 yansıtan
tek bir experiment_config sözlüğü alır (prompt, test
paketi, puanlayıcılar); 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 yazılmıştır.

Kimlik / uç nokta

Sunucu / taşıma

Taşıma seçme

opik-mcp, HTTP taşıması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) opik-backend'e olduğu gibi iletilir; kimlik doğrulama zorunluluğunun
tek noktası burasıdır. Taşımayı dağıtım şekline göre seçin:

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ğlamayı koruyun (ve stdio'yu tercih edin).

Ollie / uzun çağrılar

Telemetri

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

Bilinen ana bilgisayar sınırlamaları

MCP spesifikasyonu, 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 ve 15 saniyelik bir bekçi kalp atışı gönderir. Gerçek durum farklılık gösterir:

• Claude Code — belgelenmiş araç çağrısı zaman aşımı yok; kalp atışı çağrıyı message_end kadar canlı tutar. Önerilir.
• Cursor — ilerlemede sıfırlanmayan sabit 60s zaman aşımı (üst akış hatası). Uzun Ollie turları 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 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ı kesilmeleri) opik_mcp.ask_ollie üzerinde hata ayıklama düzeyinde 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çinde geçerlidir, kabuğunuzda değil. Düzenlemeden sonra ana bilgisayarı yeniden başlatın.

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

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

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

Geliştirme

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

Yaygın hedefler:

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 sorun açın
• SDK / arka uç belgeleri için Opik belgeleri
• Sorular için Comet topluluk Slack'i

v2'den yükseltiyor musunuz? Eski TypeScript sunucusu npm'de opik-mcp@^2 (npx -y opik-mcp) olarak hâlâ yayınlanıyor; kaynak legacy/typescript/ altında korunuyor. Destek politikası için legacy/typescript/DEPRECATED.md bölümüne bakın.

Lisans

Apache-2.0.