Comet Opik MCP Server

offiziell

Fragen Sie Ihre Opik-Logs, Traces, Prompts und alle anderen Telemetriedaten Ihrer LLMs in natürlicher Sprache ab und analysieren Sie diese.

GitHub

211

Dokumentation

opik-mcp

Migration vom alten npx opik-mcp? Der TypeScript-Server ist veraltet und wird am 15.11.2026 abgeschaltet. Ersetzen Sie npx -y opik-mcp durch uvx opik-mcp@latest in Ihrer MCP-Client-Konfiguration. Vollständige Anleitung: legacy/typescript/MIGRATION.md.

Model Context Protocol-Server für Opik + Ollie. Verbinden Sie Ihren KI-Host (Claude Code, Cursor, VS Code Copilot, MCP Inspector) direkt mit Ihrem Opik-Arbeitsbereich – lesen Sie Traces, protokollieren Sie Scores, speichern Sie Prompt-Versionen und stellen Sie Ollie investigative Fragen, alles aus dem Chat heraus.

Entwickelt für LLM-Ingenieure, die bereits Opik nutzen und es vom gleichen KI-Assistenten aus steuern möchten, mit dem sie programmieren.

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+). Der empfohlene Weg, es auszuführen, 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-Arbeitsbereich:

OPIK_API_KEY – erhalten Sie unter comet.com/api/my/settings/.
OPIK_WORKSPACE – Ihr Arbeitsbereichsname (Kleinbuchstaben, wie in der URL). Z. B. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Optional – Standard ist default (die Opik-SDK-Konvention), was für lokale/OSS-Installationen korrekt ist; Cloud-Nutzer mit einem benannten Arbeitsbereich sollten ihn setzen. COMET_WORKSPACE wird als veralteter Alias akzeptiert.

Vorabversions-Hinweis: opik-mcp (Python) ist noch nicht auf PyPI veröffentlicht. Bis zur ersten PyPI-Veröffentlichung ersetzen Sie uvx opik-mcp in jedem unten stehenden Snippet durch: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE ist optional. Lassen Sie die Zeile/den Schlüssel OPIK_WORKSPACE in jedem unten stehenden Snippet weg, und der Server verwendet den Arbeitsbereich default (korrekt für lokale/OSS-Installationen). Setzen Sie ihn nur, wenn Sie sich mit einem benannten Cloud-Arbeitsbereich verbinden.

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 erscheinen. Fragen Sie dann im Chat: "list my Opik projects" – Claude ruft das list-Tool auf und Sie sehen die Projekte Ihres Arbeitsbereichs.

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 nicht bei Fortschrittsbenachrichtigungen zurücksetzt. Lange ask_ollie-Durchläufe schlagen bei Cursor fehl. Siehe Bekannte Host-Limits.

VS Code Copilot

.vscode/mcp.json in Ihrem Arbeitsbereich (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 liegt) 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 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 "Zeige mir X"-Frage. Nimmt einen entity_type plus eine id (UUID oder, für benennbare Typen, einen Namen) oder eine vollständige opik://-URI. Zusammengesetzte Lesevorgänge (trace, prompt) betten ihre Kinder ein, sodass ein einzelner Aufruf das vollständige Bild liefert.

Unterstützte Entitäten: project, trace, span, test_suite, experiment, prompt. 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 Arbeitsbereich und kann Schreibvorgänge (Scores, Kommentare, Test-Suite-Elemente, Prompt-Versionen) bei Bedarf mitten im Prozess 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 mitten im Prozess ausfü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 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`	Eine numerische Feedback-Bewertung 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 auf eine Test-Suite beschränkt 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 die genaue JSON-Form und die erforderlichen Felder einer beliebigen Schreiboperation ein, 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 Experimentform 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 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 jeden authentifizierten Lese-/Schreibzugriff.
`OPIK_WORKSPACE`	`default`	Arbeitsbereichsname. Optional – fällt zurück auf `default` (Opik-SDK-Konvention). Cloud-Nutzer mit einem benannten Arbeitsbereich 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 Arbeitsbereichs-UUID. Wird in Analyseereignisse gestempelt, wenn gesetzt, damit BI eine stabile ID anstelle des (änderbaren) Arbeitsbereichsnamens 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 liegt.
`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-Autorisierungsserver-URL, beworben in `/.well-known/oauth-protected-resource` (RFC 9728) und als Proxy-Ziel für AS-Discovery-Sonden verwendet. Erforderlich für MCP-Hosts, um den OAuth-Tanz über HTTP zu starten.
`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`	Stderr-Logger-Schwellenwert.

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 → entferntes 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 Standardbindung 127.0.0.1 bei (und bevorzugen Sie stdio) in gemeinsam genutzten Netzwerken.

Ollie / lange Aufrufe

Variable	Standard	Hinweise
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` um eine Genehmigung pro Aktion zu verlangen, bevor Ollies Schreibvorgänge mitten im Prozess 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 mitten im Prozess auf den Benutzer warten darf, bevor sie als Abbruch behandelt wird. `0` deaktiviert die Begrenzung (nur Debugging).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie-Pod-Kaltstart-Abfrageobergrenze.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Kaltstart-Abfrageintervall.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Watchdog-Takt – 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- Digest Ihres API-Schlüssels ist enthalten, 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 alle 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-Einschränkungen

Die MCP-Spezifikation erlaubt Hosts, ihr Tool-Aufruf-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-Aufruf-Timeout; der Heartbeat hält den Aufruf am Leben, bis message_end. 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_TIMEOUT begrenzt die Gesamtdauer (Standard 60s). Erhöhen Sie sie in der Inspector-Benutzeroberfläche für lange Operationen.

Wenn ein Aufruf hängen bleibt, setzen Sie OPIK_MCP_LOG_LEVEL=DEBUG — Heartbeat-Fehler (normalerweise Host-Verbindungsabbrüche) werden auf opik_mcp.ask_ollie auf Debug-Ebene 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, wenn sie innerhalb des env-Blocks der MCP-Serverkonfiguration stehen, nicht in Ihrer Shell. Starten Sie den Host nach der Bearbeitung neu.

ask_ollie gibt nach 2 Minuten „Pod nicht bereit“ 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 selbst gehosteten Installationen.

Cursor-Aufruf läuft bei 60s ab — bekannter Cursor-Bug, nicht opik-mcp. Entweder die Ollie-Abfrage verkürzen oder denselben Vorgang in Claude Code ausführen, das keine harte Obergrenze hat.

Entwicklung

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

Gängige Ziele:

Ziel	Was es tut
`make install`	`uv sync --extra dev`
`make run`	Führt den MCP-Server aus (standardmäßig stdio).
`make run-dev`	Ausführen mit DEBUG-Protokollierung + uvicorn `--reload`.
`make dev`	Ausführen über `mcp dev` (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 unter legacy/typescript/ erhalten. Siehe legacy/typescript/DEPRECATED.md für die Support-Richtlinie.

Lizenz

Apache-2.0.