Comet Opik MCP Server

oficial

Query and analyze your Opik logs, traces, prompts and all other telemtry data from your LLMs in natural language.

Documentación

opik-mcp

¿Migrando desde el antiguo npx opik-mcp? El servidor TypeScript está obsoleto y se retirará el 2026-11-15. Cambia npx -y opik-mcp por uvx opik-mcp@latest en la configuración de tu cliente MCP. Guía completa: legacy/typescript/MIGRATION.md.

Servidor del Protocolo de Contexto de Modelo para Opik + Ollie. Conecta tu asistente de IA (Claude Code, Cursor, VS Code Copilot, MCP Inspector) directamente a tu espacio de trabajo de Opik — lee trazas, registra puntuaciones, guarda versiones de prompts y haz preguntas de investigación a Ollie, todo desde el chat.

Creado para ingenieros de LLM que ya usan Opik y quieren controlarlo desde el mismo asistente de IA con el que programan.

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

Instalación

opik-mcp es un paquete de Python (requiere Python 3.13+). La forma recomendada de ejecutarlo es uvx, que obtiene y ejecuta la última versión publicada bajo demanda — sin instalación global, sin malabares con virtualenv.

Instala uv una vez:

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

Necesitarás dos cosas de tu espacio de trabajo de Opik:

OPIK_API_KEY — consíguela en comet.com/api/my/settings/.
OPIK_WORKSPACE — el nombre de tu espacio de trabajo (en minúsculas, tal como aparece en la URL). Ej. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Opcional — por defecto es default (la convención del SDK de Opik), que es correcto para instalaciones locales/OSS; los usuarios de la nube con un espacio de trabajo con nombre deben configurarlo. COMET_WORKSPACE se acepta como un alias obsoleto.

Nota previa al lanzamiento: opik-mcp (Python) aún no está publicado en PyPI. Hasta que se publique la primera versión en PyPI, reemplaza uvx opik-mcp en cualquier fragmento a continuación por: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE es opcional. Omite la línea/clave OPIK_WORKSPACE en cualquier fragmento a continuación y el servidor usará el espacio de trabajo default (correcto para instalaciones locales/OSS). Configúralo solo si te conectas a un espacio de trabajo con nombre en la nube.

Claude Code

Añade el servidor con un comando:

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

O edita ~/.claude.json directamente:

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

Reinicia Claude Code. Verifica con /mcp — opik-mcp debería aparecer como conectado. Luego, en el chat, pregunta: "listar mis proyectos de Opik" — Claude llamará a la herramienta list y verás los proyectos de tu espacio de trabajo.

Cursor

Edita ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto), o abre Cmd+Shift+J → Funciones → Protocolo de Contexto de Modelo:

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

Recarga Cursor; el punto verde junto a opik-mcp en el panel MCP confirma la conexión. Pregunta en el chat: "listar mis proyectos de Opik".

Timeout de 60s en Cursor. Cursor impone un límite de tiempo estricto para las llamadas a herramientas que no se reinicia con notificaciones de progreso. Las tareas largas de ask_ollie fallarán en Cursor. Consulta Límites conocidos del host.

VS Code Copilot

.vscode/mcp.json en tu espacio de trabajo (o en el JSON de Configuración de Usuario):

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

Recarga la ventana; el indicador MCP de Copilot Chat muestra opik-mcp una vez que el servidor está accesible. Pregunta en el chat: "listar mis proyectos de Opik".

MCP Inspector (pruebas manuales)

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

Opik autoalojado

Añade COMET_URL_OVERRIDE (y OPIK_URL si Opik reside en una ruta no predeterminada) al mismo bloque env en la configuración de tu host:

{
  "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 y run_experiment solo están disponibles en Comet Cloud — en instalaciones autoalojadas esas llamadas fallarán al enviarse, así que usa read / list / write directamente. Configurar OPIK_MCP_ANALYTICS_SOURCE="" excluye tu instalación de la etiqueta de origen cloud-Comet en los eventos de telemetría.

Herramientas

opik-mcp expone una superficie pequeña y orientada a resultados — seis herramientas que cubren el ciclo de vida completo (leer → anotar → curar → crear → iterar).

Herramienta	Propósito
`read`	Lectura universal por id / nombre / URI `opik://`
`list`	Listado universal con filtro de nombre opcional + paginación
`ask_ollie`	Investigar / sintetizar a través del asistente integrado de Opik
`write`	Escritura universal — registrar trazas/spans, puntuar, comentar, guardar prompts, gestionar conjuntos de prueba y experimentos
`schema`	Inspeccionar esquemas de operaciones de escritura (usado por el LLM para construir cargas útiles válidas)
`run_experiment`	Ejecutar un experimento de evaluación de principio a fin a través de Ollie

`read`

Una herramienta para cualquier pregunta de "muéstrame X". Toma un entity_type más un id (UUID o, para tipos nombrables, un nombre) o una URI opik:// completa. Las lecturas compuestas (trace, prompt) incluyen sus elementos secundarios para que una sola llamada devuelva la imagen completa.

Entidades soportadas: project, trace, span, test_suite, experiment, prompt. La búsqueda por nombre está disponible para project, experiment, prompt, test_suite (más lenta — dos llamadas a la API — y puede devolver múltiples coincidencias).

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

`list`

Explora una colección con filtro de nombre opcional y paginación. Los tipos con ámbito de proyecto (trace, test_suite_item, prompt_version) requieren el UUID de su proyecto padre.

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`

Para preguntas de investigación, síntesis entre entidades o cualquier cosa que necesite experiencia en el dominio de Opik. Ollie tiene acceso de lectura directo a tu espacio de trabajo y puede ejecutar escrituras (puntuaciones, comentarios, elementos de conjuntos de prueba, versiones de prompts) en medio del flujo cuando se le solicite.

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

Devuelve el texto final del asistente más un thread_id. Pásalo de vuelta en consultas de seguimiento para preservar el contexto — Ollie no tiene memoria entre hilos.

Modo YOLO (predeterminado). Las escrituras que Ollie realiza en medio del flujo se ejecutan sin una confirmación por acción. Cada autoaprobación se registra como una fila de auditoría JSON en el logger de Python opik_mcp.audit. Para requerir confirmación en su lugar, configura OPIK_MCP_AUTO_APPROVE=disabled — las solicitudes de confirmación de Ollie aparecerán entonces como errores tipados que puedes reemitir manualmente.

Disponible solo en Comet Cloud.

`write`

Despachador de escritura universal. Pasa operation + data y el despachador valida la carga útil, aplica el verbo REST correcto y devuelve la respuesta del backend.

Operaciones:

Operación	Qué hace
`trace.create`	Registrar una sola traza (o un lote). Padre para spans / puntuaciones / comentarios.
`trace.update`	Finalizar o modificar una traza existente.
`span.create`	Registrar un span en una traza existente (o un lote).
`score.create`	Adjuntar una puntuación numérica de feedback a una traza, span o hilo.
`comment.create`	Adjuntar un comentario de texto libre a una traza, span o hilo.
`prompt_version.save`	Guardar una nueva versión de prompt (crea el prompt por nombre si no existe).
`test_suite.create`	Crear un conjunto de prueba de evaluación.
`test_suite_item.upsert`	Insertar o actualizar elementos en un conjunto de prueba (siempre con la forma de envoltura).
`experiment.create`	Crear un experimento limitado a un conjunto de prueba.
`experiment_item.create`	Adjuntar filas de traza + dataset_item a un experimento.

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

`schema`

Inspecciona la forma JSON exacta y los campos requeridos de cualquier operación de escritura antes de llamarla — útil cuando no estás seguro de cómo debería verse data. Devuelve el esquema, el ámbito OAuth y un ejemplo validado. Consulta pura, sin llamada al backend.

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

`run_experiment`

Ejecuta un experimento de evaluación de principio a fin a través de Ollie. Toma un único dict experiment_config que refleja la forma del experimento de Opik (prompt, conjunto de prueba, puntuadores); Ollie ejecuta la corrida y escribe los resultados de vuelta como un experimento de 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 solo en Comet Cloud.

Configuración

Cada ajuste es una variable de entorno. Las obligatorias en negrita.

Identidad / endpoint

Variable	Predeterminado	Notas
`OPIK_API_KEY`	—	Requerida para `ask_ollie` y cualquier lectura/escritura autenticada.
`OPIK_WORKSPACE`	`default`	Nombre del espacio de trabajo. Opcional — por defecto es `default` (convención del SDK de Opik). Los usuarios de la nube con un espacio de trabajo con nombre deben configurarlo.
`COMET_WORKSPACE`	—	Alias obsoleto para `OPIK_WORKSPACE` (compatibilidad hacia atrás). `OPIK_WORKSPACE` prevalece si ambos están configurados.
`COMET_WORKSPACE_ID`	—	UUID opcional del espacio de trabajo. Se incluye en los eventos de analítica cuando se configura para que BI pueda unir por un id estable en lugar del nombre de espacio de trabajo (mutable).
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Configúralo con tu host de Comet autoalojado, o `https://dev.comet.com` para staging.
`OPIK_URL`	derivado de `COMET_URL_OVERRIDE` + `/opik/api`	Anula solo si Opik reside en un host/ruta diferente a la UI de Comet.
`OPIK_DEFAULT_PROJECT_NAME`	no configurado	Cuando se configura, el blob `instructions` por sesión le dice al LLM que pase esto como `project_name` en cada llamada a herramienta a menos que el usuario nombre un proyecto diferente.

Servidor / transporte

Variable	Predeterminado	Notas
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` para lanzado por el host, `streamable-http` para escuchar en un puerto.
`OPIK_MCP_HOST`	`127.0.0.1`	Host de enlace de uvicorn (solo `streamable-http`).
`OPIK_MCP_PORT`	`8080`	Puerto de enlace de uvicorn (solo `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	`true` para habilitar `--reload` de uvicorn (solo desarrollo).
`OPIK_MCP_AS_URL`	no configurado	URL del Servidor de Autorización OAuth, anunciada en `/.well-known/oauth-protected-resource` (RFC 9728) y usada como el destino proxy para las sondas de descubrimiento de AS. Requerida para que los hosts MCP inicien el baile OAuth sobre HTTP.
`OPIK_MCP_RESOURCE_URI`	no configurado	URI pública canónica de este servidor, anunciada como `resource` en los metadatos del recurso protegido y usada para derivar la pista `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Umbral del logger stderr.

Elegir un transporte

opik-mcp no realiza validación de credenciales local en el transporte HTTP: cualquier Authorization: Bearer … bien formado (una clave API de Opik o un token de acceso OAuth opik_mcp_at_…) se reenvía textualmente a opik-backend, que es el punto único de aplicación de autenticación. Elige el transporte según la forma de despliegue:

Escenario	Transporte
Cliente MCP y Opik en la misma máquina (instalación OSS local)	stdio (recomendado — más simple, sin puerto, sin configuración OAuth)
Cliente MCP local → Opik remoto (nube Comet / autoalojado)	stdio con `OPIK_API_KEY`, o HTTP con OAuth (`OPIK_MCP_AS_URL` apuntando al backend)
opik-mcp alojado detrás del mismo edge que opik-backend	HTTP — los bearers son validados por el backend por solicitud

Nota para instalaciones OSS locales: el backend OSS no autentica solicitudes, por lo que un opik-mcp HTTP frente a él es tan abierto como la propia API REST OSS. Mantén el enlace predeterminado 127.0.0.1 (y prefiere stdio) en redes compartidas.

Ollie / llamadas largas

Variable	Predeterminado	Notas
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` para requerir una aprobación por acción antes de que procedan las escrituras en medio del flujo de Ollie. En hosts que anuncian la capacidad MCP `elicitation` el usuario ve un prompt sí/no; en hosts más simples la solicitud aparece como un error tipado que puedes reemitir manualmente.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Cuánto tiempo puede esperar el prompt de confirmación en medio del flujo de Ollie al usuario antes de tratarse como una cancelación. `0` desactiva el límite (solo depuración).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Límite de sondeo para el arranque en frío del pod de Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Intervalo de sondeo para el arranque en frío.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Cadencia del watchdog — emite un tick `notifications/progress` cuando el pod está en silencio, manteniendo a raya los timeouts del host.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Límite máximo de silencio del pod antes de que `ask_ollie` aborte. `0` desactiva (solo depuración).

Telemetría

Eventos de uso anónimos (solo tipo de evento + tiempo — sin contenido de consulta). Se incluye un resumen SHA-256 de tu clave API para que el soporte pueda encontrar tu cuenta; la clave en bruto nunca sale del proceso. Excluirse: OPIK_MCP_ANALYTICS_ENABLED=false.

Variable	Predeterminado	Notas
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Establecer en `false` para deshabilitar toda la telemetría.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Sobrescritura para staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Etiqueta en cada evento (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	El receptor usa esto para marcar `on_prem=False`. Las instalaciones on-prem deben sobrescribir a `""` o su propio dominio.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Tiempo de espera de conexión HTTP.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Tiempo de espera total de solicitud HTTP.

Límites conocidos del host

La especificación MCP permite a los hosts reiniciar su tiempo de espera de llamada de herramienta en notifications/progress — opik-mcp emite uno por evento SSE de Ollie más un latido de vigilancia de 15 segundos. La realidad es desigual:

Claude Code — sin tiempo de espera de llamada de herramienta documentado; el latido mantiene la llamada viva hasta message_end. Recomendado.
Cursor — tiempo de espera fijo de 60s que no se reinicia con el progreso (error conocido). Las ejecuciones largas de Ollie fallarán. Mantén las consultas de ask_ollie enfocadas.
MCP Inspector — MAX_TOTAL_TIMEOUT limita la duración total (predeterminado 60s). Auméntalo en la interfaz del Inspector para operaciones largas.

Si una llamada se bloquea, establece OPIK_MCP_LOG_LEVEL=DEBUG — las fallas de latido (generalmente desconexiones del host) se registran en opik_mcp.ask_ollie a nivel debug.

Solución de problemas

OPIK_API_KEY is required to use ask_ollie — la variable no está llegando al proceso del servidor. En Claude Code / Cursor / VS Code, las variables de entorno solo aplican cuando están dentro del bloque env de la configuración del servidor MCP, no en tu shell. Reinicia el host después de editar.

ask_ollie devuelve "pod no listo" después de 2 minutos — el arranque en frío del pod de Ollie excedió OPIK_MCP_POD_READY_TIMEOUT_S. Reintenta — la segunda llamada generalmente alcanza un pod caliente.

ask_ollie / run_experiment falla con un error de despacho en Opik autogestionado — esas herramientas solo están disponibles en Comet Cloud. Usa read / list / write directamente en autogestionado.

La llamada de Cursor expira a los 60s — error conocido de Cursor, no de opik-mcp. Acorta la consulta de Ollie o ejecuta la misma operación en Claude Code que no tiene límite fijo.

Desarrollo

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

Objetivos comunes:

Objetivo	Qué hace
`make install`	`uv sync --extra dev`
`make run`	Ejecuta el servidor MCP (stdio por defecto).
`make run-dev`	Ejecuta con registro DEBUG + uvicorn `--reload`.
`make dev`	Ejecuta vía `mcp dev` (envoltorio modo desarrollo del Inspector).
`make inspect`	Inicia MCP Inspector contra un servidor en ejecución.
`make test`	`uv run pytest -q`.
`make test-live`	Prueba en vivo de extremo a extremo contra `dev.comet.com` (establece `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + verificación de formato.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Estructura del repositorio:

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

Obtener ayuda

Abrir un issue para errores y solicitudes de funcionalidades
Documentación de Opik para documentación del SDK / backend
Comet community Slack para preguntas

¿Actualizando desde v2? El servidor TypeScript heredado todavía se distribuye en npm como opik-mcp@^2 (npx -y opik-mcp); el código fuente se conserva en legacy/typescript/. Consulta legacy/typescript/DEPRECATED.md para la política de soporte.

Licencia

Apache-2.0.