Comet Opik
offiziellFragen Sie Ihre Opik-Logs, Traces, Prompts und alle anderen Telemetriedaten Ihrer LLMs in natürlicher Sprache ab und analysieren Sie diese.
Was kann man mit Comet Opik MCP machen?
- Browse and search your Opik workspace — list projects, experiments, traces, spans, prompts, or test suites with optional name filters and pagination via
list. - Inspect any entity by ID, name, or URI — retrieve full details (including inlined children for traces and prompts) using
readwithopik://URIs or UUIDs. - Log traces, scores, comments, and prompt versions — create or update traces and spans, attach feedback scores, save prompt versions, and manage test suites through
write. - Ask Ollie investigative questions about your LLM observability data — query
ask_ollieto compare experiments, diagnose regressions, or synthesize cross-entity insights with optional mid-stream scoring. - Run evaluation experiments end-to-end — trigger
run_experimentwith a prompt, test suite, and scorers to execute and log a full evaluation run. - Introspect write operation schemas — use
schemato retrieve the exact JSON shape and required fields for any write operation before constructing a payload.
Dokumentation
Opik MCP Server
Der offizielle Model Context Protocol (MCP) Server für Opik, die Open-Source-Plattform für LLM-Beobachtbarkeit und -Evaluierung, entwickelt von Comet. Verbinden Sie Ihren KI-Host (Claude Code, Cursor, VS Code Copilot, MCP Inspector) direkt mit Ihrem Opik-Workspace: Lesen Sie Traces, protokollieren Sie Scores, speichern Sie Prompt-Versionen und stellen Sie Ollie, Opiks produktinternem KI-Assistenten, investigative Fragen – alles aus dem Chat heraus.
Entwickelt für LLM-Ingenieure, die Opik bereits nutzen und es direkt aus demselben KI-Assistenten steuern möchten, mit dem sie programmieren.
Migration vom alten
npx opik-mcp? Der TypeScript-Server ist veraltet und wird am 15.11.2026 eingestellt. Ersetzen Sienpx -y opik-mcpdurchuvx opik-mcp@latestin Ihrer MCP-Client-Konfiguration. Vollständige Anleitung: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
Installation
opik-mcp ist ein Python-Paket (benötigt Python 3.13+). Die empfohlene Art der
Ausführung ist uvx, das die neueste veröffentlichte Version bei Bedarf abruft und ausführt –
keine globale Installation, kein Hantieren mit Virtualenvs.
Installieren Sie uv einmalig:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
# or: brew install uv
Sie benötigen zwei Dinge aus Ihrem Opik-Workspace:
OPIK_API_KEY– erhalten Sie untercomet.com/api/my/settings/.OPIK_WORKSPACE– Ihr Workspace-Name (Kleinbuchstaben, wie in der URL). Z. B.https://www.comet.com/acme-ai/...→OPIK_WORKSPACE=acme-ai. Optional – Standard istdefault(die Opik-SDK-Konvention), was für lokale/OSS-Installationen korrekt ist; Cloud-Nutzer mit einem benannten Workspace sollten ihn setzen.COMET_WORKSPACEwird als veralteter Alias akzeptiert.
Vorabversions-Hinweis:
opik-mcp(Python) ist noch nicht auf PyPI veröffentlicht. Bis die erste PyPI-Version verfügbar ist, ersetzen Sieuvx opik-mcpin jedem der folgenden Snippets durch:uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp
OPIK_WORKSPACEist optional. Lassen Sie die Zeile/den SchlüsselOPIK_WORKSPACEin jedem der folgenden Snippets weg, und der Server verwendet dendefault-Workspace (korrekt für lokale/OSS-Installationen). Setzen Sie ihn nur, wenn Sie eine Verbindung zu einem benannten Cloud-Workspace herstellen.
Claude Code
Fügen Sie den Server mit einem Befehl hinzu:
claude mcp add --transport stdio opik-mcp \
--env OPIK_API_KEY=<your-key> \
--env OPIK_WORKSPACE=<your-workspace> \
-- uvx opik-mcp
Oder bearbeiten Sie ~/.claude.json direkt:
{
"mcpServers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_API_KEY": "<your-key>",
"OPIK_WORKSPACE": "<your-workspace>"
}
}
}
}
Starten Sie Claude Code neu. Überprüfen Sie mit /mcp – opik-mcp sollte als verbunden angezeigt werden.
Fragen Sie dann im Chat: "list my Opik projects" – Claude ruft das list-Tool auf
und Sie sehen die Projekte Ihres Workspaces.
Cursor
Bearbeiten Sie ~/.cursor/mcp.json (global) oder .cursor/mcp.json (Projekt), oder öffnen Sie
Cmd+Shift+J → Features → Model Context Protocol:
{
"mcpServers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_API_KEY": "<your-key>",
"OPIK_WORKSPACE": "<your-workspace>"
}
}
}
}
Laden Sie Cursor neu; der grüne Punkt neben opik-mcp im MCP-Bedienfeld bestätigt die
Verbindung. Fragen Sie im Chat: "list my Opik projects".
Cursor 60s Timeout. Cursor erzwingt ein hartes Tool-Aufruf-Timeout, das sich bei Fortschrittsbenachrichtigungen nicht zurücksetzt. Lange
ask_ollie-Durchläufe schlagen in Cursor fehl. Siehe Bekannte Host-Limits.
VS Code Copilot
.vscode/mcp.json in Ihrem Workspace (oder den Benutzereinstellungen JSON):
{
"servers": {
"opik-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["opik-mcp"],
"env": {
"OPIK_API_KEY": "<your-key>",
"OPIK_WORKSPACE": "<your-workspace>"
}
}
}
}
Laden Sie das Fenster neu; die Copilot Chat MCP-Anzeige zeigt opik-mcp, sobald
der Server erreichbar ist. Fragen Sie im Chat: "list my Opik projects".
MCP Inspector (manuelles Testen)
OPIK_API_KEY=<your-key> OPIK_WORKSPACE=<your-workspace> \
npx @modelcontextprotocol/inspector uvx opik-mcp
Selbst gehostetes Opik
Fügen Sie COMET_URL_OVERRIDE (und OPIK_URL, falls Opik unter einem nicht standardmäßigen Pfad läuft) zum
gleichen env-Block in Ihrer Host-Konfiguration hinzu:
{
"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 und run_experiment sind nur in der Comet Cloud verfügbar – bei
selbst gehosteten Installationen schlagen diese Aufrufe bei der Ausführung fehl, verwenden Sie daher read / list / write
direkt. Das Setzen von OPIK_MCP_ANALYTICS_SOURCE="" deaktiviert das
Cloud-Comet-Quelllabel bei Telemetrieereignissen für Ihre Installation.
Tools
opik-mcp bietet eine kleine, ergebnisorientierte Oberfläche – sechs Tools, die
den gesamten Lebenszyklus abdecken (Lesen → Annotieren → Kuratieren → Erstellen → Iterieren).
| Tool | Zweck |
|---|---|
read | Universelles Lesen nach ID / Name / opik://-URI |
list | Universelles Auflisten mit optionalem Namensfilter + Paginierung |
ask_ollie | Untersuchen / Synthetisieren über den produktinternen Opik-Assistenten |
write | Universelles Schreiben – Traces/Spans protokollieren, bewerten, kommentieren, Prompts speichern, Test-Suites & Experimente verwalten |
schema | Schreiboperations-Schemata einsehen (wird vom LLM verwendet, um gültige Payloads zu erstellen) |
run_experiment | Ein Evaluierungsexperiment Ende-zu-Ende über Ollie ausführen |
read
Ein Tool für jede "Zeig mir X"-Frage. Nimmt einen entity_type plus eine id
(UUID oder, für benennbare Typen, einen Namen) oder eine vollständige opik://-URI entgegen. Zusammengesetzte Lesevorgänge
(trace, prompt) betten ihre untergeordneten Elemente ein, sodass ein einzelner Aufruf das vollständige
Bild liefert.
Unterstützte Entitäten: project, trace, span, test_suite, experiment,
prompt. Die namensbasierte Suche ist verfügbar für project, experiment, prompt,
test_suite (langsamer – zwei API-Aufrufe – und kann mehrere Treffer zurückgeben).
read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo") # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
list
Durchsuchen Sie eine Sammlung mit optionalem Namensfilter und Paginierung. Projektbezogene
Typen (trace, test_suite_item, prompt_version) benötigen ihre übergeordnete UUID.
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
Für investigative Fragen, entitätsübergreifende Synthesen oder alles, was Opik-Domänenexpertise erfordert. Ollie hat direkten Lesezugriff auf Ihren Workspace und kann Schreibvorgänge (Scores, Kommentare, Test-Suite-Elemente, Prompt-Versionen) bei Bedarf im laufenden Betrieb ausführen.
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.")
Gibt den endgültigen Text des Assistenten plus eine thread_id zurück. Übergeben Sie diese bei
Folgefragen, um den Kontext zu erhalten – Ollie hat kein Gedächtnis über Threads hinweg.
YOLO-Modus (Standard). Schreibvorgänge, die Ollie im laufenden Betrieb durchführt, werden ohne
Bestätigung pro Aktion ausgeführt. Jede automatische Genehmigung wird als JSON-Audit-Zeile im
opik_mcp.audit Python-Logger protokolliert. Um stattdessen eine Bestätigung zu verlangen, setzen Sie
OPIK_MCP_AUTO_APPROVE=disabled – Ollies Bestätigungsanfragen erscheinen dann als
typisierte Fehler, die Sie manuell erneut ausgeben können.
Nur in der Comet Cloud verfügbar.
write
Universeller Schreib-Dispatcher. Übergeben Sie operation + data und der Dispatcher
validiert die Payload, wendet das richtige REST-Verb an und gibt die
Backend-Antwort zurück.
Operationen:
| Operation | Beschreibung |
|---|---|
trace.create | Einen einzelnen Trace (oder einen Stapel) protokollieren. Übergeordnet für Spans / Scores / Kommentare. |
trace.update | Einen bestehenden Trace finalisieren oder ändern. |
span.create | Einen Span für einen bestehenden Trace protokollieren (oder einen Stapel). |
score.create | Einen numerischen Feedback-Score an einen Trace, Span oder Thread anhängen. |
comment.create | Einen Freitext-Kommentar an einen Trace, Span oder Thread anhängen. |
prompt_version.save | Eine neue Prompt-Version speichern (erstellt den Prompt nach Namen, falls nicht vorhanden). |
test_suite.create | Eine Evaluierungs-Test-Suite erstellen. |
test_suite_item.upsert | Elemente in eine Test-Suite einfügen oder aktualisieren (immer die Envelope-Form). |
experiment.create | Ein Experiment erstellen, das einer Test-Suite zugeordnet ist. |
experiment_item.create | Trace- und Dataset-Item-Zeilen an ein Experiment anhängen. |
write(operation="score.create", data={
"target": "trace",
"target_id": "7f2e3c8a-…",
"name": "helpfulness",
"value": 0.9,
"reason": "great recovery"
})
schema
Sehen Sie sich die genaue JSON-Form und die erforderlichen Felder einer beliebigen Schreiboperation an, bevor
Sie sie aufrufen – nützlich, wenn Sie nicht sicher sind, wie data aussehen sollte. Gibt
das Schema, den OAuth-Bereich und ein validiertes Beispiel zurück. Reine Suche, kein Backend-
Aufruf.
schema(operation="score.create")
schema(operation="prompt_version.save")
run_experiment
Führen Sie ein Evaluierungsexperiment Ende-zu-Ende über Ollie aus. Nimmt ein einzelnes
experiment_config-Dictionary entgegen, das die Experiment-Form von Opik widerspiegelt (Prompt, Test-
Suite, Scorer); Ollie führt den Durchlauf aus und schreibt die Ergebnisse als Opik-
Experiment zurück.
run_experiment(experiment_config={
"test_suite_name": "qa-eval-v2",
"prompt_name": "welcome-msg",
# … see `schema(operation="experiment.create")` for the full shape
})
Nur in der Comet Cloud verfügbar.
Konfiguration
Jede Einstellung ist eine Umgebungsvariable. Erforderliche sind fett markiert.
Identität / Endpunkt
| Variable | Standard | Hinweise |
|---|---|---|
OPIK_API_KEY | — | Erforderlich für ask_ollie und alle authentifizierten Lese-/Schreibvorgänge. |
OPIK_WORKSPACE | default | Workspace-Name. Optional – Fallback auf default (Opik-SDK-Konvention). Cloud-Nutzer mit einem benannten Workspace sollten ihn setzen. |
COMET_WORKSPACE | — | Veralteter Alias für OPIK_WORKSPACE (Abwärtskompatibilität). OPIK_WORKSPACE hat Vorrang, wenn beide gesetzt sind. |
COMET_WORKSPACE_ID | — | Optionale Workspace-UUID. Wird in Analyseereignisse gestempelt, wenn gesetzt, damit BI eine stabile ID anstelle des (änderbaren) Workspace-Namens verwenden kann. |
COMET_URL_OVERRIDE | https://www.comet.com | Auf Ihren selbst gehosteten Comet-Host setzen, oder https://dev.comet.com für Staging. |
OPIK_URL | abgeleitet von COMET_URL_OVERRIDE + /opik/api | Nur überschreiben, wenn Opik auf einem anderen Host/Pfad als die Comet-UI läuft. |
OPIK_DEFAULT_PROJECT_NAME | nicht gesetzt | Wenn gesetzt, weist der instructions-Blob pro Sitzung das LLM an, dies als project_name bei jedem Tool-Aufruf zu übergeben, es sei denn, der Benutzer nennt ein anderes Projekt. |
Server / Transport
| Variable | Standard | Hinweise |
|---|---|---|
OPIK_MCP_TRANSPORT | stdio | stdio für vom Host gestartet, streamable-http um auf einem Port zu lauschen. |
OPIK_MCP_HOST | 127.0.0.1 | Uvicorn-Bind-Host (nur streamable-http). |
OPIK_MCP_PORT | 8080 | Uvicorn-Bind-Port (nur streamable-http). |
OPIK_MCP_RELOAD | false | true um Uvicorn --reload zu aktivieren (nur Entwicklung). |
OPIK_MCP_AS_URL | nicht gesetzt | OAuth Authorization Server URL, beworben in /.well-known/oauth-protected-resource (RFC 9728) und als Proxy-Ziel für AS-Discovery-Sonden verwendet. Erforderlich, damit MCP-Hosts den OAuth-Ablauf über HTTP starten können. |
OPIK_MCP_RESOURCE_URI | nicht gesetzt | Kanonische öffentliche URI dieses Servers, beworben als resource in den Metadaten der geschützten Ressource und verwendet, um den WWW-Authenticate-Hinweis abzuleiten. |
OPIK_MCP_LOG_LEVEL | INFO | Schwellenwert für den Stderr-Logger. |
Auswahl eines Transports
opik-mcp führt keine lokale Anmeldeinformationsvalidierung beim HTTP-Transport durch: jedes
wohlgeformte Authorization: Bearer … (ein Opik-API-Schlüssel oder ein opik_mcp_at_…
OAuth-Zugriffstoken) wird unverändert an das Opik-Backend weitergeleitet, das die
einzige Instanz zur Authentifizierungserzwingung ist. Wählen Sie den Transport je nach Bereitstellungsform:
| Szenario | Transport |
|---|---|
| MCP-Client und Opik auf demselben Rechner (lokale OSS-Installation) | stdio (empfohlen – am einfachsten, kein Port, kein OAuth-Setup) |
| Lokaler MCP-Client → Remote Opik (Comet Cloud / selbst gehostet) | stdio mit OPIK_API_KEY, oder HTTP mit OAuth (OPIK_MCP_AS_URL zeigt auf das Backend) |
| Gehostetes opik-mcp hinter demselben Edge wie das Opik-Backend | HTTP – Bearer werden pro Anfrage vom Backend validiert |
Hinweis für lokale OSS-Installationen: Das OSS-Backend authentifiziert keine Anfragen,
daher ist ein HTTP-opik-mcp davor so offen wie die OSS-REST-API selbst.
Behalten Sie die standardmäßige 127.0.0.1-Bindung bei (und bevorzugen Sie stdio) in gemeinsam genutzten Netzwerken.
Ollie / lange Aufrufe
| Variable | Standard | Hinweise |
|---|---|---|
OPIK_MCP_AUTO_APPROVE | enabled | disabled um eine Bestätigung pro Aktion zu verlangen, bevor Ollies Schreibvorgänge im laufenden Betrieb fortgesetzt werden. Bei Hosts, die die MCP-elicitation-Fähigkeit bewerben, sieht der Benutzer eine Ja/Nein-Aufforderung; bei einfacheren Hosts erscheint die Anfrage als typisierter Fehler, den Sie manuell erneut ausgeben können. |
OPIK_MCP_ELICIT_TIMEOUT_SECONDS | 60 | Wie lange Ollies Bestätigungsaufforderung im laufenden Betrieb auf den Benutzer warten darf, bevor sie als Abbruch behandelt wird. 0 deaktiviert die Begrenzung (nur Debugging). |
OPIK_MCP_POD_READY_TIMEOUT_S | 120 | Obergrenze für Ollie Pod-Kaltstartabfragen. |
OPIK_MCP_POD_READY_INTERVAL_S | 2 | Intervall für Kaltstartabfragen. |
OPIK_MCP_HEARTBEAT_INTERVAL_S | 15.0 | Watchdog-Taktung – sendet einen notifications/progress-Tick, wenn der Pod still ist, und hält Host-Timeouts in Schach. |
OPIK_MCP_STREAM_IDLE_TIMEOUT_S | 300.0 | Harte Obergrenze für Pod-Stille, bevor ask_ollie abbricht. 0 deaktiviert (nur Debugging). |
Telemetrie
Anonyme Nutzungsereignisse (nur Ereignistyp + Zeitmessung — kein Abfrageinhalt). Ein SHA-256-Hash Ihres API-Schlüssels wird einbezogen, damit der Support Ihr Konto finden kann; der rohe Schlüssel verlässt niemals den Prozess. Opt-out: OPIK_MCP_ANALYTICS_ENABLED=false.
| Variable | Standard | Hinweise |
|---|---|---|
OPIK_MCP_ANALYTICS_ENABLED | true | Auf false setzen, um sämtliche Telemetrie zu deaktivieren. |
OPIK_MCP_ANALYTICS_URL | https://stats.comet.com/notify/event/ | Überschreibung für Staging. |
OPIK_MCP_ANALYTICS_ENVIRONMENT | prod | Tag für jedes Ereignis (prod / staging / dev). |
OPIK_MCP_ANALYTICS_SOURCE | comet.com | Der Empfänger verwendet dies, um on_prem=False zu markieren. On-Prem-Installationen sollten auf "" oder ihre eigene Domain überschreiben. |
OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S | 5.0 | HTTP-Verbindungs-Timeout. |
OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S | 10.0 | HTTP-Gesamtanforderungs-Timeout. |
Bekannte Host-Limits
Die MCP-Spezifikation erlaubt Hosts, ihr Tool-Call-Timeout bei notifications/progress zurückzusetzen — opik-mcp sendet eines pro Ollie-SSE-Ereignis plus einen 15-Sekunden-Watchdog-Heartbeat. Die Realität ist uneinheitlich:
- Claude Code — kein dokumentiertes Tool-Call-Timeout; der Heartbeat hält den Aufruf bis
message_endam Leben. Empfohlen. - Cursor — hartes 60s-Timeout, das nicht bei Fortschritt zurückgesetzt wird (Upstream-Bug). Lange Ollie-Ausführungen werden fehlschlagen. Halten Sie
ask_ollie-Abfragen fokussiert. - MCP Inspector —
MAX_TOTAL_TIMEOUTbegrenzt die Gesamtdauer (Standard 60s). Erhöhen Sie den Wert in der Inspector-UI für lange Operationen.
Falls ein Aufruf hängen bleibt, setzen Sie OPIK_MCP_LOG_LEVEL=DEBUG — Heartbeat-Fehler (normalerweise Host-Disconnects) werden auf opik_mcp.ask_ollie im Debug-Level protokolliert.
Fehlerbehebung
OPIK_API_KEY is required to use ask_ollie — die Variable erreicht den Serverprozess nicht. In Claude Code / Cursor / VS Code gelten Umgebungsvariablen nur innerhalb des env-Blocks der MCP-Serverkonfiguration, nicht in Ihrer Shell. Starten Sie den Host nach der Bearbeitung neu.
ask_ollie gibt nach 2 Minuten "pod not ready" zurück — der Kaltstart des Ollie-Pods hat OPIK_MCP_POD_READY_TIMEOUT_S überschritten. Wiederholen Sie den Vorgang — der zweite Aufruf trifft normalerweise einen warmen Pod.
ask_ollie / run_experiment schlägt mit einem Dispatch-Fehler bei selbst gehostetem Opik fehl — diese Tools sind nur in Comet Cloud verfügbar. Verwenden Sie read / list / write direkt bei Selbsthosting.
Cursor-Aufruf läuft bei 60s in Timeout — bekannter Cursor-Bug, nicht opik-mcp. Verkürzen Sie entweder die Ollie-Abfrage oder führen Sie dieselbe Operation in Claude Code aus, das keine harte Obergrenze hat.
Entwicklung
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
Gängige Ziele:
| Ziel | Beschreibung |
|---|---|
make install | uv sync --extra dev |
make run | MCP-Server ausführen (standardmäßig stdio). |
make run-dev | Mit DEBUG-Logging + uvicorn --reload ausführen. |
make dev | Über mcp dev ausführen (Inspector-Dev-Mode-Wrapper). |
make inspect | MCP Inspector gegen einen laufenden Server starten. |
make test | uv run pytest -q. |
make test-live | Live-End-to-End gegen dev.comet.com (setzen Sie OPIK_API_KEY + OPIK_WORKSPACE). |
make lint | ruff check + Formatprüfung. |
make format | ruff format + ruff check --fix. |
make typecheck | mypy. |
make check | lint + typecheck + test. |
Repo-Layout:
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
Hilfe erhalten
- Ein Issue eröffnen für Bugs und Feature-Requests
- Opik-Dokumentation für SDK-/Backend-Dokumentation
- Comet Community Slack für Fragen
Upgrade von v2? Der alte TypeScript-Server wird weiterhin auf npm als
opik-mcp@^2(npx -y opik-mcp) ausgeliefert; der Quellcode bleibt unterlegacy/typescript/erhalten. Siehelegacy/typescript/DEPRECATED.mdfür die Support-Richtlinie.
Lizenz
Apache-2.0.