Comet Opik

officiel

Interrogez et analysez vos logs Opik, traces, prompts et toutes autres données de télémétrie de vos LLMs en langage naturel.

GitHub

217

Que pouvez-vous faire avec Comet Opik MCP ?

Parcourir et rechercher votre espace de travail Opik — lister les projets, expériences, traces, spans, prompts ou suites de tests avec des filtres de nom facultatifs et une pagination via list.
Inspecter toute entité par ID, nom ou URI — récupérer les détails complets (y compris les enfants intégrés pour les traces et les prompts) en utilisant read avec des URI opik:// ou des UUID.
Journaliser les traces, scores, commentaires et versions de prompts — créer ou mettre à jour des traces et spans, attacher des scores de feedback, enregistrer des versions de prompts et gérer les suites de tests via write.
Poser des questions d'investigation à Ollie sur vos données d'observabilité LLM — interroger ask_ollie pour comparer des expériences, diagnostiquer des régressions ou synthétiser des informations transversales avec un scoring en cours de flux facultatif.
Exécuter des expériences d'évaluation de bout en bout — déclencher run_experiment avec un prompt, une suite de tests et des scoreurs pour exécuter et journaliser une évaluation complète.
Inspecter les schémas des opérations d'écriture — utiliser schema pour récupérer la forme JSON exacte et les champs requis pour toute opération d'écriture avant de construire une charge utile.

Documentation

Serveur MCP Opik

Le serveur officiel Model Context Protocol (MCP) pour Opik, la plateforme open-source d'observabilité et d'évaluation LLM, conçue par Comet. Connectez directement votre hôte IA (Claude Code, Cursor, VS Code Copilot, MCP Inspector) à votre espace de travail Opik : lisez les traces, enregistrez des scores, sauvegardez des versions de prompts et posez des questions d'investigation à Ollie, l'assistant IA intégré à Opik, le tout depuis le chat.

Conçu pour les ingénieurs LLM qui utilisent déjà Opik et souhaitent le piloter depuis le même assistant IA avec lequel ils codent.

Migration depuis l'ancien npx opik-mcp ? Le serveur TypeScript est obsolète et sera retiré le 15 novembre 2026. Remplacez npx -y opik-mcp par uvx opik-mcp@latest dans la configuration de votre client MCP. Guide complet : 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 est un package Python (nécessite Python 3.13+). La méthode recommandée pour l'exécuter est uvx, qui récupère et exécute la dernière version publiée à la demande — pas d'installation globale, pas de jonglage avec virtualenv.

Installez uv une fois :

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

Vous aurez besoin de deux éléments de votre espace de travail Opik :

OPIK_API_KEY — obtenez-la depuis comet.com/api/my/settings/.
OPIK_WORKSPACE — le nom de votre espace de travail (en minuscules, tel qu'il apparaît dans l'URL). Par exemple, https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Facultatif — valeur par défaut default (la convention du SDK Opik), ce qui est correct pour les installations locales/OSS ; les utilisateurs cloud avec un espace de travail nommé doivent le définir. COMET_WORKSPACE est accepté comme alias obsolète.

Note préliminaire : opik-mcp (Python) n'est pas encore publié sur PyPI. Jusqu'à la première publication sur PyPI, remplacez uvx opik-mcp dans tout extrait ci-dessous par : uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE est facultatif. Omettez la ligne/clé OPIK_WORKSPACE dans tout extrait ci-dessous et le serveur utilise l'espace de travail default (correct pour les installations locales/OSS). Ne le définissez que si vous vous connectez à un espace de travail cloud nommé.

Claude Code

Ajoutez le serveur avec une seule commande :

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

Ou modifiez directement ~/.claude.json :

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

Redémarrez Claude Code. Vérifiez avec /mcp — opik-mcp devrait apparaître comme connecté. Ensuite, dans le chat, demandez : "list my Opik projects" — Claude appellera l'outil list et vous verrez les projets de votre espace de travail.

Cursor

Modifiez ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projet), ou ouvrez Cmd+Shift+J → Fonctionnalités → Model Context Protocol :

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

Rechargez Cursor ; le point vert à côté de opik-mcp dans le panneau MCP confirme la connexion. Demandez dans le chat : "list my Opik projects".

Timeout de 60s de Cursor. Cursor impose un délai strict d'appel d'outil qui ne se réinitialise pas sur les notifications de progression. Les longs appels ask_ollie échoueront sur Cursor. Voir Limites connues des hôtes.

VS Code Copilot

.vscode/mcp.json dans votre espace de travail (ou JSON des paramètres utilisateur) :

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

Rechargez la fenêtre ; l'indicateur MCP du chat Copilot affiche opik-mcp une fois le serveur accessible. Demandez dans le chat : "list my Opik projects".

MCP Inspector (test manuel)

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

Opik auto-hébergé

Ajoutez COMET_URL_OVERRIDE (et OPIK_URL si Opik réside à un chemin non standard) au même bloc env dans la configuration de votre hôte :

{
  "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 et run_experiment sont disponibles uniquement sur Comet Cloud — en auto-hébergé, ces appels échoueront à l'envoi, utilisez donc read / list / write directement. Définir OPIK_MCP_ANALYTICS_SOURCE="" exclut votre installation de l'étiquette source cloud-Comet sur les événements de télémétrie.

Outils

opik-mcp expose une surface réduite et orientée résultats — six outils qui couvrent le cycle de vie complet (lire → annoter → organiser → créer → itérer).

Outil	Objectif
`read`	Lecture universelle par id / nom / URI `opik://`
`list`	Liste universelle avec filtre de nom optionnel + pagination
`ask_ollie`	Investiguer / synthétiser via l'assistant intégré d'Opik
`write`	Écriture universelle — enregistrer traces/spans, scorer, commenter, sauvegarder des prompts, gérer les suites de tests et les expériences
`schema`	Introspecter les schémas des opérations d'écriture (utilisé par le LLM pour construire des charges valides)
`run_experiment`	Exécuter une expérience d'évaluation de bout en bout via Ollie

`read`

Un outil pour toute question "montre-moi X". Prend un entity_type plus un id (UUID ou, pour les types nommables, un nom) ou une URI opik:// complète. Les lectures composites (trace, prompt) intègrent leurs enfants, de sorte qu'un seul appel renvoie l'image complète.

Entités prises en charge : project, trace, span, test_suite, experiment, prompt. La recherche par nom est disponible pour project, experiment, prompt, test_suite (plus lente — deux appels API — et peut renvoyer plusieurs correspondances).

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

`list`

Parcourir une collection avec un filtre de nom optionnel et une pagination. Les types liés au projet (trace, test_suite_item, prompt_version) nécessitent l'UUID de leur parent.

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`

Pour les questions d'investigation, la synthèse inter-entités ou tout ce qui nécessite une expertise du domaine Opik. Ollie a un accès direct en lecture à votre espace de travail et peut exécuter des écritures (scores, commentaires, éléments de suite de tests, versions de prompts) en cours de route lorsqu'on le lui demande.

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

Renvoie le texte final de l'assistant plus un thread_id. Transmettez-le lors des suivis pour préserver le contexte — Ollie n'a pas de mémoire entre les fils de discussion.

Mode YOLO (par défaut). Les écritures qu'Ollie effectue en cours de route s'exécutent sans confirmation par action. Chaque auto-approbation est journalisée sous forme de ligne d'audit JSON sur le logger Python opik_mcp.audit. Pour exiger une confirmation à la place, définissez OPIK_MCP_AUTO_APPROVE=disabled — les demandes de confirmation d'Ollie apparaissent alors comme des erreurs typées que vous pouvez réémettre manuellement.

Disponible sur Comet Cloud uniquement.

`write`

Répartiteur d'écriture universel. Passez operation + data et le répartiteur valide la charge utile, applique le verbe REST approprié et renvoie la réponse du backend.

Opérations :

Opération	Ce qu'elle fait
`trace.create`	Enregistrer une trace unique (ou un lot). Parent pour les spans / scores / commentaires.
`trace.update`	Finaliser ou modifier une trace existante.
`span.create`	Enregistrer une span sur une trace existante (ou un lot).
`score.create`	Attacher un score de feedback numérique à une trace, une span ou un fil de discussion.
`comment.create`	Attacher un commentaire en texte libre à une trace, une span ou un fil de discussion.
`prompt_version.save`	Sauvegarder une nouvelle version de prompt (crée le prompt par nom s'il est manquant).
`test_suite.create`	Créer une suite de tests d'évaluation.
`test_suite_item.upsert`	Insérer ou mettre à jour des éléments dans une suite de tests (toujours la forme enveloppe).
`experiment.create`	Créer une expérience limitée à une suite de tests.
`experiment_item.create`	Attacher des lignes de trace + dataset_item à une expérience.

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

`schema`

Inspectez la forme JSON exacte et les champs requis de toute opération d'écriture avant de l'appeler — utile lorsque vous n'êtes pas sûr de ce à quoi data devrait ressembler. Renvoie le schéma, la portée OAuth et un exemple validé. Recherche pure, aucun appel backend.

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

`run_experiment`

Exécutez une expérience d'évaluation de bout en bout via Ollie. Prend un seul dict experiment_config qui reflète la forme d'expérience d'Opik (prompt, suite de tests, évaluateurs) ; Ollie exécute l'analyse et écrit les résultats en retour sous forme d'expérience Opik.

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

Disponible sur Comet Cloud uniquement.

Configuration

Chaque paramètre est une variable d'environnement. Les obligatoires sont en gras.

Identité / point de terminaison

Variable	Valeur par défaut	Notes
`OPIK_API_KEY`	—	Obligatoire pour `ask_ollie` et toute lecture/écriture authentifiée.
`OPIK_WORKSPACE`	`default`	Nom de l'espace de travail. Facultatif — valeur de repli `default` (convention du SDK Opik). Les utilisateurs cloud avec un espace de travail nommé doivent le définir.
`COMET_WORKSPACE`	—	Alias obsolète pour `OPIK_WORKSPACE` (rétrocompatibilité). `OPIK_WORKSPACE` l'emporte si les deux sont définis.
`COMET_WORKSPACE_ID`	—	UUID facultatif de l'espace de travail. Intégré dans les événements d'analyse lorsqu'il est défini afin que la BI puisse joindre sur un identifiant stable plutôt que sur le nom (modifiable) de l'espace de travail.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Définissez-le sur votre hôte Comet auto-hébergé, ou `https://dev.comet.com` pour le staging.
`OPIK_URL`	dérivé de `COMET_URL_OVERRIDE` + `/opik/api`	À remplacer uniquement si Opik réside sur un hôte/chemin différent de l'interface utilisateur Comet.
`OPIK_DEFAULT_PROJECT_NAME`	non défini	Lorsqu'il est défini, le blob `instructions` par session indique au LLM de le transmettre comme `project_name` à chaque appel d'outil, sauf si l'utilisateur nomme un projet différent.

Serveur / transport

Variable	Valeur par défaut	Notes
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` pour le lancement par l'hôte, `streamable-http` pour écouter sur un port.
`OPIK_MCP_HOST`	`127.0.0.1`	Hôte de liaison uvicorn (`streamable-http` uniquement).
`OPIK_MCP_PORT`	`8080`	Port de liaison uvicorn (`streamable-http` uniquement).
`OPIK_MCP_RELOAD`	`false`	`true` pour activer `--reload` d'uvicorn (dev uniquement).
`OPIK_MCP_AS_URL`	non défini	URL du serveur d'autorisation OAuth, annoncée dans `/.well-known/oauth-protected-resource` (RFC 9728) et utilisée comme cible proxy pour les sondes de découverte AS. Obligatoire pour que les hôtes MCP amorcent la danse OAuth via HTTP.
`OPIK_MCP_RESOURCE_URI`	non défini	URI publique canonique de ce serveur, annoncée comme `resource` dans les métadonnées de la ressource protégée et utilisée pour dériver l'indice `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Seuil du logger stderr.

Choisir un transport

opik-mcp n'effectue aucune validation locale des informations d'identification sur le transport HTTP : tout Authorization: Bearer … bien formé (une clé API Opik ou un jeton d'accès OAuth opik_mcp_at_…) est transmis tel quel au backend opik, qui est le point unique d'application de l'authentification. Choisissez le transport en fonction de la forme de déploiement :

Scénario	Transport
Client MCP et Opik sur la même machine (installation OSS locale)	stdio (recommandé — le plus simple, pas de port, pas de configuration OAuth)
Client MCP local → Opik distant (Comet cloud / auto-hébergé)	stdio avec `OPIK_API_KEY`, ou HTTP avec OAuth (`OPIK_MCP_AS_URL` pointant vers le backend)
opik-mcp hébergé derrière la même périphérie que le backend opik	HTTP — les porteurs sont validés par le backend à chaque requête

Note pour les installations OSS locales : le backend OSS n'authentifie pas les requêtes, donc un opik-mcp HTTP devant lui est aussi ouvert que l'API REST OSS elle-même. Conservez la liaison 127.0.0.1 par défaut (et préférez stdio) sur les réseaux partagés.

Ollie / appels longs

Variable	Valeur par défaut	Notes
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` pour exiger une approbation par action avant que les écritures en cours de route d'Ollie ne se poursuivent. Sur les hôtes qui annoncent la capacité MCP `elicitation`, l'utilisateur voit une invite oui/non ; sur les hôtes plus simples, la demande apparaît comme une erreur typée que vous pouvez réémettre manuellement.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Durée pendant laquelle l'invite de confirmation en cours de route d'Ollie peut attendre l'utilisateur avant d'être traitée comme une annulation. `0` désactive la limite (débogage uniquement).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Limite d'interrogation du démarrage à froid du pod Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Intervalle d'interrogation du démarrage à froid.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Cadence du chien de garde — émet un tick `notifications/progress` lorsque le pod est silencieux, tenant les timeouts de l'hôte à distance.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Plafond strict du silence du pod avant que `ask_ollie` n'abandonne. `0` désactive (débogage uniquement).

Télémétrie

Événements d'utilisation anonymes (type d'événement + durée uniquement — aucun contenu de requête). Un condensat SHA-256 de votre clé API est inclus afin que le support puisse retrouver votre compte ; la clé brute ne quitte jamais le processus. Désactiver : OPIK_MCP_ANALYTICS_ENABLED=false.

Variable	Valeur par défaut	Remarques
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Définir sur `false` pour désactiver toute télémétrie.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Remplacement pour l'environnement de staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Balise sur chaque événement (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Le récepteur utilise ceci pour marquer `on_prem=False`. Les installations sur site doivent le remplacer par `""` ou leur propre domaine.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Délai de connexion HTTP.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Délai total de la requête HTTP.

Limites connues des hôtes

La spécification MCP permet aux hôtes de réinitialiser leur délai d'appel d'outil sur notifications/progress — opik-mcp émet un événement par événement SSE Ollie plus un signal de surveillance de 15 secondes. La réalité est inégale :

Claude Code — aucun délai d'appel d'outil documenté ; le signal de surveillance maintient l'appel actif jusqu'à message_end. Recommandé.
Cursor — délai strict de 60s qui ne se réinitialise pas sur progression (bug upstream). Les longs appels Ollie échoueront. Gardez les requêtes ask_ollie ciblées.
MCP Inspector — MAX_TOTAL_TIMEOUT limite la durée totale (60s par défaut). Augmentez-la dans l'interface de l'Inspector pour les opérations longues.

Si un appel se bloque, définissez OPIK_MCP_LOG_LEVEL=DEBUG — les échecs de signal de surveillance (généralement des déconnexions de l'hôte) sont journalisés sur opik_mcp.ask_ollie au niveau debug.

Dépannage

OPIK_API_KEY is required to use ask_ollie — la variable n'atteint pas le processus serveur. Dans Claude Code / Cursor / VS Code, les variables d'environnement ne s'appliquent qu'à l'intérieur du bloc env de la configuration du serveur MCP, pas dans votre shell. Redémarrez l'hôte après modification.

ask_ollie renvoie "pod not ready" après 2 minutes — le démarrage à froid du pod Ollie a dépassé OPIK_MCP_POD_READY_TIMEOUT_S. Réessayez — le deuxième appel atteint généralement un pod chaud.

ask_ollie / run_experiment échoue avec une erreur de dispatch sur Opik auto-hébergé — ces outils sont disponibles uniquement sur Comet Cloud. Utilisez read / list / write directement sur l'auto-hébergé.

L'appel Cursor expire à 60s — bug connu de Cursor, pas opik-mcp. Soit raccourcissez la requête Ollie, soit exécutez la même opération sur Claude Code qui n'a pas de limite stricte.

Développement

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

Cibles courantes :

Cible	Ce qu'elle fait
`make install`	`uv sync --extra dev`
`make run`	Exécute le serveur MCP (stdio par défaut).
`make run-dev`	Exécute avec la journalisation DEBUG + uvicorn `--reload`.
`make dev`	Exécute via `mcp dev` (wrapper mode développeur Inspector).
`make inspect`	Lance MCP Inspector contre un serveur en cours d'exécution.
`make test`	`uv run pytest -q`.
`make test-live`	Test de bout en bout en direct contre `dev.comet.com` (définissez `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + vérification de format.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Structure du dépôt :

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

Obtenir de l'aide

Ouvrir un ticket pour les bugs et les demandes de fonctionnalités
Documentation Opik pour la documentation SDK / backend
Slack de la communauté Comet pour les questions

Mise à niveau depuis la v2 ? Le serveur TypeScript hérité est toujours distribué sur npm sous opik-mcp@^2 (npx -y opik-mcp) ; la source est conservée sous legacy/typescript/. Voir legacy/typescript/DEPRECATED.md pour la politique de support.

Licence

Apache-2.0.