Comet Opik

oficial

Consulta y analiza tus registros de Opik, trazas, prompts y todos los demás datos de telemetría de tus LLMs en lenguaje natural.

GitHub

226

¿Qué puedes hacer con Comet Opik MCP?

Consultar trazas por proyecto — Pregunta qué trazas de un proyecto han fallado hoy, con filtros por información de errores, duración o uso de tokens.
Leer cualquier entidad de Opik — Obtén un proyecto, una traza, un span, un conjunto de datos, un experimento, un prompt, un hilo o un problema de Diagnostics por id, nombre o URI opik://.
Registrar puntuaciones y comentarios — Puntúa una traza con una métrica de feedback y un motivo, o añade comentarios mediante la herramienta de escritura.
Guardar versiones de prompts — Crea y almacena nuevas versiones de prompts junto con conjuntos de datos y experimentos.
Inspeccionar esquemas de escritura — Solicita el esquema de una operación de escritura para crear una carga útil válida antes de enviarla.
Comprobar el estado del proyecto — Lee un proyecto para obtener el número de trazas, la tasa de errores, la duración media y el coste total de los últimos 7 días.

Documentación

Servidor MCP de Opik

El servidor oficial del Model Context Protocol (MCP) para Opik, la plataforma de código abierto de observabilidad y evaluación de LLM, creada por Comet. Conecta tu host de IA (Claude Code, Cursor, VS Code Copilot, Codex, opencode o cualquier cliente MCP) directamente con tu espacio de trabajo de Opik: lee trazas, registra puntuaciones y guarda versiones de prompts, todo desde el chat.

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

You:    "Which traces in project 'demo' failed today?"
Claude: → list(entity_type="trace", project_name="demo") → "Three traces failed…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

Inicio rápido

Un solo comando configura Opik en los clientes de IA de tu máquina, incluido Claude Code. Detecta tu Opik (el guardado en ~/.opik.config, uno que se esté ejecutando en localhost o te pregunta cuál), registra el servidor MCP, instala el paquete de habilidades de Opik y comprueba la conexión. En Opik Cloud no hay que gestionar ninguna clave de API: tu cliente inicia sesión en el navegador. Necesita uv y ningún SDK de Opik:

uvx opik@latest mcp configure

Sin terminal, por ejemplo desde un agente de programación o un script, indica el cliente:

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client también acepta codex, cursor, vscode y opencode. Si lo ejecutas así, usa el Opik guardado en ~/.opik.config, incluida la clave de API, o uno que responda en localhost; de lo contrario, se detiene y pregunta por --deployment.

Si se le pide a un agente de programación que «instale opik mcp», encontrará todos los pasos, incluido qué preguntarle al usuario, en uvx opik-mcp@latest --help. Son los mismos que los de Instalar con un agente de programación más abajo.

Registrar el servidor manualmente, con los comandos del cliente en Configurar manualmente, omite la comprobación de qué Opik usas y el paquete de habilidades, por lo que está pensado para clientes que el instalador no admite.

Tu Opik	Servidor	Transporte	Inicio de sesión
Opik Cloud (`www.comet.com`)	el servidor alojado, gestionado por Comet	Streamable HTTP	en el navegador (OAuth); sin clave de API
Comet autohospedado, Opik de código abierto	el servidor local, este paquete	stdio	variables de entorno; una clave de API solo cuando la implementación la necesita

Los clientes cargan los servidores MCP al iniciar una sesión, así que inicia una sesión nueva después.

Guía de configuración, solución de problemas y preguntas frecuentes: comet.com/docs/opik/mcp-server.

Opik Cloud: el servidor alojado

Comet ejecuta el servidor en https://www.comet.com/opik/api/v1/mcp. Tu cliente se conecta por HTTP y abre el navegador para iniciar sesión la primera vez. No hay nada que instalar, ninguna clave de API ni espacio de trabajo que configurar: el servidor funciona en el espacio de trabajo que elijas al iniciar sesión. Después de añadirlo, inicia una sesión nueva y pregunta: «lista mis proyectos de Opik».

El comando de Inicio rápido lo configura para Claude Code, Codex, Cursor, VS Code Copilot y opencode, junto con el paquete de habilidades. En Claude Code, el plugin hace lo mismo con un solo comando. Los botones de abajo lo añaden a Cursor o VS Code con un solo clic; encontrarás otras formas de registrarlo manualmente en Configurar manualmente.

Plugin de Claude Code

El plugin opik instala las habilidades de Opik y registra el servidor MCP alojado para Opik Cloud:

/plugin install opik --marketplace comet-ml/opik-mcp

En Claude Code anterior a la versión 2.1.275, ejecuta /plugin marketplace add comet-ml/opik-mcp, y luego /plugin install opik@opik. Las habilidades se cargan como opik:<skill>, por ejemplo opik:opik-instrument, y /mcp muestra el servidor como plugin:opik:opik-cloud. El servidor es el de Opik Cloud. Inicia una sesión nueva y luego inicia sesión desde /mcp → Authenticate. Para un Comet autohospedado que ejecute el servidor MCP OAuth, añádelo con claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; para cualquier otro Opik autohospedado o de código abierto, usa el comando de Inicio rápido. Luego desactiva plugin:opik:opik-cloud en /mcp. Claude Code no actualiza por sí solo un plugin de este marketplace: ejecuta /plugin marketplace update opik y luego /plugin update opik@opik, o activa las actualizaciones automáticas del marketplace en /plugin. Este marketplace sirve main, que puede ser más reciente que la última versión publicada. Solo se recibe una actualización cuando cambia la versión del plugin, con cada lanzamiento.

Si ya habías añadido opik-mcp con la misma URL, Claude Code conserva tu copia y omite la del plugin. Si la tuya es otro servidor, como el servidor local uvx opik-mcp, se cargan ambos: ejecuta claude mcp remove opik-mcp para conservar solo el del plugin. Las habilidades del paquete también se cargan junto a las copias del plugin; elimínalas con npx skills remove --global --agent claude-code, que te preguntará cuáles.

Opik autohospedado y de código abierto: el servidor local

opik-mcp se ejecuta en tu máquina: el cliente lo inicia con uvx opik-mcp y se comunica con él por stdio. El comando de Inicio rápido lo configura a partir de tu ~/.opik.config o de un Opik local; para registrarlo manualmente, consulta Configurar manualmente. Instala uv una vez; en el primer uso descarga el paquete y Python 3.13 si hace falta:

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

uvx opik-mcp reutiliza la copia que uv tiene en caché, por lo que se inicia rápidamente; uv cache clean opik-mcp hace que el siguiente inicio descargue la versión más reciente. uvx opik-mcp@latest consulta PyPI en cada inicio, lo que añade aproximadamente un segundo y medio. Codex espera mcp_optional_startup_grace_ms (1 s de forma predeterminada) a que los servidores estén listos antes de crear la primera lista de herramientas, así que un inicio más lento puede dejar las herramientas fuera del primer turno. Los comandos puntuales de este README (opik mcp configure, opik mcp status, --help, --check) incluyen @latest, por lo que nunca ejecutan una copia que uv haya guardado en caché hace meses.

Las variables de entorno indican al servidor dónde está tu Opik:

Tu Opik	Variables de entorno
Opik de código abierto en esta máquina	`OPIK_URL=http://localhost:5173/api`
Opik de código abierto en un servidor	`OPIK_URL=https://<host>/api`, además de `OPIK_API_KEY` solo si la implementación añade autenticación
Plataforma Comet autohospedada (la interfaz de Opik está en `https://<host>/opik`)	`COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY`

La versión de código abierto ofrece su API en /api y tiene un solo espacio de trabajo, default, así que no necesita OPIK_WORKSPACE. COMET_URL_OVERRIDE dirigiría el servidor a /opik/api, que la versión de código abierto no ofrece.
Una plataforma Comet autohospedada tiene espacios de trabajo con nombre. Configura OPIK_WORKSPACE con el segmento que aparece después de /opik/ en tu URL de Opik; si lo omites, las lecturas se hacen desde el espacio de trabajo predeterminado de tu cuenta, sin ningún error que lo indique.
Una plataforma Comet autohospedada que ejecute el servidor MCP OAuth (desactivado de forma predeterminada) puede usar el flujo alojado en https://<host>/opik/api/v1/mcp.
Sustituye todos los valores. El servidor rechaza un espacio de trabajo de marcador de posición como <your-workspace> o ${input:OPIK_WORKSPACE}; una URL de marcador de posición se envía tal cual y no logra conectarse.
OPIK_MCP_ANALYTICS_SOURCE="" en el bloque env excluye una instalación autohospedada de la etiqueta de origen de Comet Cloud en los eventos de telemetría.

Antes de añadir el servidor a un cliente, comprueba la configuración: ejecútalo con el mismo entorno y --check. Hace una llamada a Opik e imprime el espacio de trabajo y cuántos proyectos encuentra, o qué debes corregir junto con un enlace a la documentación, y termina con el código 0 o 1. Un cliente no puede informarte de esto antes de iniciar una sesión nueva: Claude Code muestra «Connected» incluso con una clave incorrecta, y Codex no inicia nada hasta entonces.

OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check

Luego regístralo con tu cliente: el servidor local, manualmente.

Instalar con un agente de programación

Para un agente de IA al que se le pide instalar el servidor, por ejemplo, «instala opik mcp». El objetivo es registrar el servidor para el Opik del usuario, instalar el paquete de habilidades de Opik e iniciar sesión. Averigua qué Opik se usa en esta máquina y pregunta al usuario solo lo que no puedas determinar: una pregunta por mensaje y espera cada respuesta antes de hacer la siguiente. El instalador del paso 3 realiza toda la configuración de una vez, así que resuelve los pasos 1 y 2 antes de ejecutarlo. uvx opik-mcp@latest --help muestra estos pasos.

Comprueba qué hay.
```
uvx opik@latest mcp status
```
Muestra el Opik guardado en ~/.opik.config (URL y espacio de trabajo, nunca la clave) y los clientes que ya tienen el servidor. En Claude Code, ejecuta también claude mcp list: muestra los conectores de claude.ai y las entradas con otros nombres. También imprime el comando de cada entrada, que en una entrada antigua de npx puede contener una clave de API: no la repitas.
- Un servidor para https://www.comet.com/opik/api/v1/mcp con cualquier nombre, como un conector de claude.ai, significa que ya está registrado: no añadas otro. Instala el paquete de habilidades por separado con npx skills add comet-ml/opik-skills -g --all. Ve al paso 4 si el servidor aparece como ! Needs authentication.
- El instalador reemplaza sin preguntar una entrada existente de opik-mcp, como una del antiguo servidor npx. Pregúntale al usuario antes de ejecutarlo.
Averigua qué Opik usa el usuario.
- Guardado en ~/.opik.config: úsalo e indica al usuario cuál estás configurando. El instalador lo lee, incluida la clave de API, así que no pidas una clave.
- No hay ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. Una respuesta indica que hay un Opik de código abierto en esta máquina. En un shell aislado, como el de Codex, que no haya respuesta puede significar que el shell no tiene conexión de red, no que no haya Opik.
- Ninguna de las dos cosas: pregunta y no elijas por tu cuenta. Una URL de Opik en el proyecto, como OPIK_URL_OVERRIDE en .env, permite hacer una pregunta de sí o no. De lo contrario: «¿Qué Opik usas: Opik Cloud (www.comet.com), un Opik de código abierto (su URL) o una plataforma Comet autohospedada (su URL y espacio de trabajo)?»

Ejecuta el instalador para el cliente que estés usando. Instala el paquete de habilidades de Opik junto con el servidor, con o sin --skills; conserva la marca en el comando que le des al usuario para que lo ejecute más adelante. En Opik Cloud, abre el navegador para iniciar sesión y espera un minuto, así que avisa al usuario antes.

uvx opik@latest mcp configure --ai-client claude-code --skills

--ai-client también acepta codex, cursor, vscode y opencode. Si el Opik está guardado en ~/.opik.config o se ejecuta en localhost, ejecútalo tal cual: --deployment aparta la configuración guardada, incluida la clave de API. Si no se cumple ninguna de esas condiciones, añade la marca correspondiente al Opik que el usuario indicó en el paso 2:

Opik del usuario	Añadir
Opik Cloud, `www.comet.com`	`--deployment cloud`
Opik de código abierto	`--deployment local`, y `--url <url>` si no está en localhost
Una plataforma Comet autohospedada, `/opik/` en su URL	`--deployment self-hosted --url <url> --workspace <workspace>`, con `OPIK_API_KEY` en el shell

Si falla, por ejemplo porque Opik no responde, dile al usuario qué mensaje apareció y qué debe comprobar, como la VPN o la URL. No cambies a otro Opik.

Inicio de sesión en Opik Cloud. Si el instalador indica que el servidor aún no ha iniciado sesión, dile al usuario que ejecute claude mcp login opik-mcp o /mcp en una sesión de Claude Code, en lugar de ejecutarlo tú: el comando espera a que se abra el navegador. Un conector de claude.ai inicia sesión desde /mcp. El inicio de sesión pide un espacio de trabajo; indica el guardado en ~/.opik.config, si lo hay.
Finaliza. Indica qué se instaló y qué queda por hacer. Menciona el paquete de habilidades: las habilidades de Opik, instaladas para todos los proyectos, que enseñan al agente a instrumentar, evaluar y depurar con Opik. Los clientes cargan los servidores MCP y las habilidades al iniciar una sesión: pide al usuario que inicie una sesión nueva y luego pruebe «lista mis proyectos de Opik».

En todos los casos:

No le pidas al usuario que pegue una clave de API en el chat. El servidor alojado no necesita ninguna; en los demás casos, tómala del entorno del shell ("$OPIK_API_KEY") o deja que el usuario ejecute el comando.
No adivines el espacio de trabajo. Es el segmento que aparece después de comet.com/opik/ (o /opik/ en una plataforma Comet autohospedada) en la URL de Opik del usuario.
No imprimas ~/.claude.json ni ~/.opik.config: ambos pueden contener claves de API. uvx opik@latest mcp status y claude mcp list muestran lo que necesitas, y el instalador lee la configuración por sí mismo.
Si una comprobación de permisos bloquea un comando, no intentes eludirla. Dale al usuario el comando que debe ejecutar (en Claude Code, ! antes de ejecutarlo desde el mensaje).

Para un cliente que el instalador no conoce, regístralo manualmente con los comandos de Configúralo manualmente: el servidor alojado para Opik Cloud y el servidor local para el resto.

Antes de registrar el servidor local, ejecútalo con el entorno que vas a pasar y --check, con OPIK_API_KEY exportado en el shell en lugar de escrito en el comando: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Sale con el código 0 y muestra el workspace que detecta, o indica qué debes corregir. Una vez registrado, Claude Code muestra Connected incluso con una clave incorrecta, y Codex no tiene ninguna comprobación.
Claude Code se niega a añadir una entrada opik-mcp existente, así que elimínala primero con claude mcp remove opik-mcp --scope user; add de Codex la reemplaza.
Después de registrarlo, en Claude Code, consulta solo la línea de estado: claude mcp get opik-mcp | grep Status. La salida completa muestra el bloque env, incluida la clave de API. El servidor alojado muestra ! Needs authentication hasta que se ejecute claude mcp login opik-mcp. Codex no tiene nada que inicie el servidor antes de una sesión; codex mcp get opik-mcp muestra lo que se guardó, con los valores del entorno ocultos.

Configúralo manualmente (sin comprobación de Opik ni paquete de skills)

El comando Inicio rápido hace todo esto para Claude Code, Codex, Cursor, VS Code Copilot y opencode, y también comprueba qué Opik usas e instala el paquete de skills. Regístralo manualmente solo para otro cliente o para ver qué escribe el instalador. Un agente de programación que instala para un usuario ejecuta el instalador: consulta Instalar con un agente de programación.

Servidor alojado (Opik Cloud)

Claude Code, manualmente

claude mcp add --scope user --transport http opik-mcp https://www.comet.com/opik/api/v1/mcp

Después, inicia sesión desde /mcp → Authenticate en una sesión de Claude Code. Se abre un navegador, así que debe hacerlo la persona que está frente al teclado; desde su propia terminal, claude mcp login opik-mcp hace lo mismo. --scope user hace que el servidor esté disponible en todos los proyectos; sin él, Claude Code lo registra solo para el directorio actual. Por SSH, claude mcp login opik-mcp --no-browser muestra la URL de inicio de sesión para abrirla en tu propio equipo; el último paso requiere un terminal interactivo (ssh -t).

Codex, manualmente

codex mcp add opik-mcp --url https://www.comet.com/opik/api/v1/mcp

add abre el inicio de sesión; codex mcp login opik-mcp lo vuelve a abrir. En ~/.codex/config.toml, el mismo servidor es:

[mcp_servers.opik-mcp]
url = "https://www.comet.com/opik/api/v1/mcp"

Cursor, manualmente

Usa el botón debajo de el servidor alojado o añádelo a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "opik-mcp": {
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

VS Code Copilot, manualmente

Usa el botón debajo de el servidor alojado o añádelo a .vscode/mcp.json en tu workspace o a tu mcp.json de usuario (MCP: Open User Configuration):

{
  "servers": {
    "opik-mcp": {
      "type": "http",
      "url": "https://www.comet.com/opik/api/v1/mcp"
    }
  }
}

Otros clientes

Cualquier cliente que acepte una URL puede usar el servidor alojado:

npx add-mcp https://www.comet.com/opik/api/v1/mcp --name opik-mcp

Un cliente que solo pueda iniciar comandos locales puede acceder a él mediante npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp.

Opik Cloud con una clave de API

Si nadie puede completar el inicio de sesión en el navegador, por ejemplo, cuando un agente se ejecuta sin supervisión desde un script o un cliente no admite MCP OAuth, usa una clave de API de comet.com/api/my/settings/ en su lugar, con el servidor local apuntando a Opik Cloud:

claude mcp add --scope user opik-mcp \
  --env OPIK_API_KEY="$OPIK_API_KEY" \
  --env OPIK_WORKSPACE=<workspace> \
  -- uvx opik-mcp

Los demás clientes usan las mismas dos variables en su bloque env. Asigna OPIK_WORKSPACE al segmento que aparece después de comet.com/opik/ en tu URL de Opik (https://www.comet.com/opik/acme-ai/projects → acme-ai). Si se omite, el servidor envía default, que Comet resuelve como el workspace predeterminado de tu cuenta, por lo que las lecturas pueden proceder del workspace equivocado sin que se produzca un error.

Servidor local (Opik autoalojado y de código abierto)

Los ejemplos usan una instancia local de Opik de código abierto. Para Comet autoalojado, sustituye las tres variables por las de la tabla. Después de añadir el servidor, inicia una sesión nueva y pregunta: "list my Opik projects".

Claude Code, manualmente

claude mcp add --scope user opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

En una instancia de Comet autoalojada, con la clave en el OPIK_API_KEY de tu shell:

claude mcp add --scope user opik-mcp \
  --env COMET_URL_OVERRIDE=https://<host> \
  --env OPIK_WORKSPACE=<workspace> \
  --env OPIK_API_KEY="$OPIK_API_KEY" \
  -- uvx opik-mcp

O edita directamente ~/.claude.json:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

claude mcp get opik-mcp muestra ✔ Connected cuando se inicia el servidor. Eso no demuestra que la URL o la clave sean correctas, porque solo una llamada a una herramienta llega a Opik; --check (el servidor local) sí lo hace. También muestra el bloque env, incluida la clave de API.

Codex, manualmente

codex mcp add opik-mcp --env OPIK_URL=http://localhost:5173/api -- uvx opik-mcp

O edita ~/.codex/config.toml:

[mcp_servers.opik-mcp]
command = "uvx"
args = ["opik-mcp"]
env = { OPIK_URL = "http://localhost:5173/api" }
# On a self-hosted Comet, forward the key from the environment Codex starts in,
# so it stays out of this file:
# env_vars = ["OPIK_API_KEY"]
# Time allowed for the server to start (default 10 s); the first start
# downloads the package.
startup_timeout_sec = 30

Codex solo proporciona a un servidor local las variables de env y los nombres de env_vars, así que, de lo contrario, una clave exportada en tu shell no llega al servidor.

Cursor, manualmente

Añádelo a ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto), o usa Cmd+Shift+J → Features → Model Context Protocol:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

Tiempo de espera de Cursor: 60 s. Cursor impone un tiempo de espera estricto para las llamadas a herramientas que no se reinicia con las notificaciones de progreso. Consulta Límites conocidos de los hosts.

VS Code Copilot, manualmente

Añádelo a .vscode/mcp.json en tu workspace o a tu mcp.json de usuario (MCP: Open User Configuration):

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_URL": "http://localhost:5173/api"
      }
    }
  }
}

MCP Inspector (pruebas manuales)

OPIK_URL=http://localhost:5173/api npx @modelcontextprotocol/inspector uvx opik-mcp

¿Vienes de `npx opik-mcp`?

El servidor TypeScript (npm opik-mcp@2) está obsoleto y dejará de atender solicitudes el 2026-11-15. Para una instalación nueva, ejecuta el comando de Inicio rápido; uvx opik-mcp es el comando que ejecuta un cliente para iniciar el servidor, no un instalador. Para migrar una configuración existente de Opik Cloud, cámbiate al servidor alojado y elimina la clave de API. De lo contrario, en la configuración de tu cliente MCP, sustituye npx -y opik-mcp por uvx opik-mcp. Se cambiaron algunas variables de entorno y ya no se leen las marcas de línea de comandos: consulta la guía de migración. Política de soporte: DEPRECATED.md. El código fuente de TypeScript está en la etiqueta git legacy-typescript-final.

Herramientas

opik-mcp ofrece una interfaz pequeña y orientada a resultados que cubre todo el ciclo de vida (leer → anotar → seleccionar → crear → iterar).

Herramienta	Propósito
`read`	Lectura universal por id / nombre / URI de `opik://`
`list`	Listado universal con filtro de nombre opcional + paginación
`write`	Escritura universal: registrar trazas/tramos, puntuar, comentar, guardar prompts, gestionar datasets y experimentos
`schema`	Inspeccionar esquemas de operaciones de escritura (el LLM los usa para construir cargas útiles válidas)
`read_skill`	Leer una de las skills de agente de Opik incluidas con este servidor

`read`

Una herramienta para cualquier pregunta del tipo «muéstrame X». Acepta un entity_type y un id (UUID o, para los tipos con nombre, un nombre) o un URI opik:// completo. Las lecturas compuestas (trace, prompt, thread, agent_insights_issue) incluyen sus elementos secundarios, de modo que una sola llamada devuelve la vista completa.

El registro que indiques se devuelve completo. Los elementos secundarios incluidos no: sus cuerpos se obtienen con truncate=true del backend, por lo que un campo de más de ~10 KB se trunca en ClickHouse y las imágenes base64 se sustituyen por "[image]"; de lo contrario, un mismo adjunto repetido en 200 tramos costaría más que todo lo demás de la lectura. La respuesta lo indica en spanBodies / messageBodies, y cualquier elemento secundario vuelve a estar completo mediante su propio read("span", id) o read("trace", trace_id), que llaman a endpoints que no tienen ningún parámetro truncate.

Las colecciones incluidas también tienen un límite de longitud: 200 tramos, 200 turnos, 100 versiones de prompts. Si se supera ese límite, spansTruncated / messagesTruncated / versionsTruncated es true y una línea moreSpans / moreMessages / moreVersions junto a ella indica el recuento y la llamada exacta a list(...) que continúa desde donde se detuvo la parte incluida.

Entidades compatibles: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. La búsqueda por nombre está disponible para project, experiment, prompt, dataset (más lenta: dos llamadas a la API, y puede devolver varias coincidencias). thread y agent_insights_issue están limitados al proyecto: pasa project_id o project_name, o un enlace/URI que incluya el proyecto. Antes, dataset y dataset_item se llamaban test_suite y test_suite_item; los nombres antiguos siguen funcionando, pero no se anuncian y el código nuevo debería usar los nuevos.

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")  # name lookup
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")
read(entity_type="agent_insights_issue", id="<issue-uuid>", project_id="<project-uuid>")
read(
    entity_type="agent_insights_issue",
    id="https://www.comet.com/opik/<ws>/projects/<pid>/diagnostics?issue=<id>",
)

Un enlace copiado de la interfaz de usuario de Opik sirve como id: un enlace a un hilo o a una página de Diagnostics incluye el proyecto, así que no se necesita project_id y el tipo de entidad se obtiene del enlace.

Una lectura de project responde «cómo va mi proyecto» en una sola llamada. Devuelve {project, summary, vocabulary, contains, url}: el registro y, después, las cuatro métricas que la página Logs muestra como tarjetas (recuento de trazas, tasa de errores, duración media, coste total) de los últimos 7 días frente a los 7 anteriores, solo tráfico del SDK, tal como aparece en pantalla. since / until cambian ese intervalo; since="30d" es lo que abre la interfaz de usuario. Una tasa o un promedio de un período sin trazas se devuelve como null, porque un 0 % de errores en una semana sin tráfico parece indicar una semana saludable.

vocabulary es el mapa que necesitas antes de poder preguntar cualquier otra cosa: los nombres de las puntuaciones de feedback del proyecto, sus claves de uso de tokens y las reglas de automatización que puntúan sus trazas. Estos son los nombres que se usan en un filtro o en series= más abajo; si los adivinas, obtendrás una página vacía que parece una buena noticia. El número de nombres de puntuaciones y reglas está limitado, pero siempre se indica el total real y la llamada que devuelve el resto; las claves de uso se enumeran completas, ya que no hay otra forma de enumerarlas. contains indica el experimento, dataset, versión del prompt y ejecución de optimización más recientes, para que «qué ha estado pasando aquí» no requiera cuatro llamadas más. Si no se pudo cargar una sección, se indica en lugar de dejarla vacía, y las secciones vacías se omiten.

Una lectura de agent_insights_issue devuelve {issue, example_trace_ids, details}: el registro del problema de Diagnostics (nombre, descripción, causa, solución sugerida, gravedad, estado), los ids deduplicados de las trazas que lo presentan (la misma muestra que muestra la página Diagnostics; abre una con read("trace", id)) y el desglose por día. Los cuerpos de las trazas no se incluyen, así que la lectura sigue siendo una sola llamada al backend. since / until limitan las filas por día; el valor predeterminado es todo el período. Cuando el servidor conoce la URL de Opik y el workspace de la sesión, la lectura también incluye url (la página Diagnostics del problema) y trace_url_template (un enlace directo a cualquiera de las trazas de ejemplo), para que el asistente pueda proporcionarte algo en lo que puedas hacer clic; en una sesión OAuth cuyo workspace no se pudo resolver, se omiten los enlaces en lugar de adivinarlos.

Las trazas no incluyen una URL: no se puede derivar un enlace a partir de los campos que devuelve un read o un list, y una estructura inventada devuelve un error 404. En su lugar, las instrucciones de la sesión indican una plantilla para ello, .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., para que el asistente complete un id y te proporcione un enlace. Pasa por la redirección de opik-backend, que resuelve el proyecto y el workspace a partir de la traza, así que funciona cuando una URL directa del proyecto no puede hacerlo, incluso en una sesión OAuth con un workspace sin resolver. Es el mismo enlace que imprime el SDK de Python para una traza.

`list`

Explora o busca una colección con paginación. Los tipos limitados al proyecto (trace, span, thread, agent_insights_issue, dataset_item, prompt_version) necesitan su elemento principal: un UUID o nombre de proyecto, un UUID de dataset o un UUID de prompt.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")  # name substring filter
list(entity_type="agent_insights_issue", project_name="demo")  # open Diagnostics issues
list(entity_type="agent_insights_issue", project_id="<uuid>", status="resolved")
list(entity_type="trace", project_name="demo")  # latest traces of one project
list(
    entity_type="trace", project_name="demo", filters="error_info is_not_empty AND duration > 5000"
)
list(
    entity_type="span",
    project_name="demo",  # spans across the whole project
    filters='type = "llm" AND usage.total_tokens > 10000',
)
list(
    entity_type="thread",
    project_name="demo",
    filters="number_of_messages > 20 AND feedback_scores.helpfulness < 0.5",
)
list(entity_type="experiment", filters='dataset_id = "<dataset-uuid>" AND tags contains "baseline"')

Filtros. trace, span, thread, experiment y dataset_item aceptan una cadena OQL, con la misma gramática que search_traces(filter_string=…) del SDK:

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

Las cadenas van entre comillas dobles, los números van sin comillas, duration está en milisegundos, las fechas son instantes ISO-8601 con zona horaria ("2026-09-08T10:00:00Z"). Las puntuaciones y los diccionarios llevan una clave: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND es el único conector.

Al igual que la página Logs de la interfaz, las listas de trazas, spans e hilos añaden source = "sdk" para que las trazas de evaluadores, del entorno de pruebas y de experimentos no estorben; indica source tú mismo para verlas. La primera línea de salida repite el filtro aplicado.

Un filtro incorrecto falla antes de llegar al backend e indica qué hace falta para corregirlo: la posición de un error de sintaxis, el nombre de campo más parecido, los operadores válidos para el tipo del campo o el formato de valor esperado. Los campos con un conjunto cerrado de valores (source, span type, hilo status, visibility_mode) también se validan contra ese conjunto, incluidos todos los elementos de una lista in. source es el único que el backend valida por sí mismo, y responde con un 500 en lugar de un 400 ante un valor desconocido, así que source = "SDK" sería un error de servidor opaco para una letra mayúscula. El resto se compara como cadenas y responde con una página vacía, que se interpreta como «sin coincidencias» cuando en realidad significa «valor inexistente». Consulta schema("list.trace") (o list.span, list.thread, list.experiment) para ver la referencia completa de campos, incluidos los valores aceptados.

Encontrar un caso en un conjunto de datos. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> para las claves con las que se creó el conjunto de datos, full_data para buscar una subcadena en todo el contenido (un escaneo completo: indica una clave cuando puedas), además de id, tags, source, trace_id, span_id y las marcas de tiempo. data.<key> solo admite los seis operadores de cadenas (=, !=, contains, not_contains, starts_with, ends_with); el backend responde con un 400 a una comparación, así que esta se rechaza antes de la llamada. El endpoint no permite ordenar ni buscar texto libre: sort se rechaza en lugar de descartarse. read(entity_type="dataset_item", id=…) devuelve un caso completo, que es la forma de recuperar un valor que la tabla recortó.

list(entity_type="dataset_item", dataset_id="<uuid>", filters='data.question contains "install"')
list(
    entity_type="dataset_item", dataset_id="<uuid>", filters='trace_id = "<trace-uuid>"'
)  # the case made from that trace
read(entity_type="dataset_item", id="<item-uuid>")  # the case, uncut

Con experiment_ids, la misma lista muestra la comparación: los casos con cada ejecución adjunta; y filtra por las ejecuciones (feedback_scores.<name>, output, duration). Son dos conjuntos de campos distintos en dos endpoints del backend: schema("list.dataset_item_case") corresponde a los casos propios del conjunto de datos, schema("list.dataset_item") a la comparación.

Ordenar. trace, span, thread y experiment aceptan sort="<field> [asc|desc]", desc de forma predeterminada y un solo campo: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". El campo se valida con la lista de campos ordenables de la entidad antes de la llamada, porque el backend ignora silenciosamente los campos por los que no puede ordenar. En espacios de trabajo muy grandes, el backend elimina por completo la ordenación; el encabezado lo indica cuando ocurre.

dataset_item solo permite ordenar en una comparación (con experiment_ids): el endpoint de elementos no acepta parámetros de ordenación, así que se rechaza ordenar una lista simple en lugar de descartarlo.

Intervalo de tiempo y búsqueda. trace, span y thread aceptan since y until, cada uno como intervalo relativo ("30m", "1h", "7d") o como instante ISO-8601 con zona horaria, así que «la última hora» no requiere cálculos de tiempo. El intervalo se basa en la hora de creación del registro, que resulta económica para el backend y coincide con start_time con una diferencia de segundos en el tráfico en tiempo real. Para un límite exacto, coloca start_time en filters. Los mismos tres tipos aceptan search, texto libre que busca coincidencias en cualquier parte del id, nombre, entrada, salida, metadatos, etiquetas e id del hilo. La búsqueda escanea todo el proyecto en el backend, así que la primera llamada en un proyecto grande puede tardar decenas de segundos. Esas llamadas tienen un tiempo de espera de 60 segundos. Añadir since vuelve a acelerarlas.

Leer la tabla. Las duraciones se etiquetan como duration_ms / ttft_ms y se muestran en milisegundos enteros; el campo sigue siendo duration en filters y sort. Las marcas de tiempo se muestran hasta el segundo y los costes como decimales sin formato. Las filas de proyectos incluyen last_updated_trace_at para que puedas ver qué proyecto tiene tráfico en tiempo real; las filas de hilos incluyen el primer mensaje. Una página vacía con un intervalo de tiempo indica cuándo llegó la última traza del proyecto, y una página vacía con el valor predeterminado source = "sdk" explica cómo ver las otras fuentes. Si escribes mal un project_name, se devuelve el nombre existente más parecido.

list(
    entity_type="trace",
    project_name="demo",
    since="1h",
    filters="error_info is_not_empty",
    sort="duration desc",
)
list(entity_type="trace", project_name="demo", search="order-42")

Problemas de Diagnostics. agent_insights_issue es la página Diagnostics a través de MCP: los fallos recurrentes que el trabajo Diagnostics de Opik agrupó para un proyecto, ordenados como en la interfaz (primero los vistos más recientemente). Las columnas son severity, status, total_occurrences (suma de todos los tiempos), latest_count (el día del informe más reciente, la fecha a la que se refiere la descripción del problema) y last_seen. De forma predeterminada, se muestran los problemas abiertos; pasa status="resolved" o "closed" para ver el resto. read y list también se aceptan como issue, que es el nombre que usa la interfaz para estos problemas; el nombre largo es el que aparece en el enum entity_type, así que esa entidad no aparece dos veces. Los recuentos son de todos los tiempos para que coincidan con la interfaz; los mismos since / until que para las trazas acotan el intervalo, truncado a días de informe UTC porque Diagnostics agrega los datos por día.

Una lista vacía explica por qué lo está, porque «no hay nada roto» y «nadie activó Diagnostics» se interpretarían igual de otro modo. Hay cinco estados: Diagnostics no está disponible en esta implementación, no está habilitado para este proyecto, está desactivado, está habilitado pero no se ha analizado recientemente, o está habilitado y limpio, con la hora del último análisis. Los estados sobre los que puedes actuar indican qué llamada hacer, y todos incluyen un enlace a la página Diagnostics del proyecto.

Una lista no vacía indica sus fechas. Los problemas son los que agrupó el último análisis, así que la respuesta termina con Report covers data through <time>; si el intervalo que solicitaste se extiende más allá de ese momento, indica el tramo final sin cubrir y cómo completarlo: con un activador cuando un nuevo análisis abarque un período suficientemente amplio; de lo contrario, con trazas sin procesar y el since que proporciona. Si solicitas una semana para un proyecto que se analiza cada noche, falta el último día en la respuesta agrupada; esto es lo que lo indica.

write("agent_insights_job.enable", {"project_name": "demo"}) activa Diagnostics. A partir de entonces, se realizan análisis diarios y es seguro volver a llamar a esta operación. write("agent_insights_job.trigger", …) analiza ahora las últimas 24 horas, sin esperar al análisis nocturno. Ambas requieren el mismo permiso que la lectura de problemas y se rechazan si la implementación no dispone de Diagnostics.

Un problema avanza por su ciclo de vida con write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) —resuelto— o con …close si no merece la pena actuar al respecto, y con …reopen para volver a incluir cualquiera de los dos en la lista de abiertos. Las tres operaciones requieren el mismo permiso y responden con un enlace a la vista a la que se trasladó el problema, ya que un problema resuelto deja de aparecer en la página predeterminada. Decidir si un fallo está corregido es cuestión de criterio, así que úsalas cuando lo solicites: el asistente no debe ordenar la lista mientras la revisa.

Métricas a lo largo del tiempo. project_metric muestra en una tabla de intervalos una métrica de un proyecto: recuentos de trazas, spans e hilos, duraciones, tasas de error, costes, uso de tokens y puntuaciones de comentarios. Responde a la pregunta que viene después de la descripción general: cuándo cambió algo.

list(entity_type="project_metric", project_name="demo", metric_type="trace_count")
list(
    entity_type="project_metric",
    project_name="demo",
    metric_type="trace_error_rate",
    since="14d",
    interval="daily",
)
list(
    entity_type="project_metric", project_name="demo", metric_type="span_count", breakdown="model"
)  # one column per model
list(
    entity_type="project_metric",
    project_name="demo",
    metric_type="span_duration",
    breakdown="model",
    series="p99",
)  # the p99 of each model

Las filas son intervalos de tiempo, no registros, así que page, size y sort se rechazan en lugar de ignorarse. interval es hourly, daily, weekly o total; si se omite, sigue el intervalo como lo hace la pestaña Metrics: por hora hasta 3 días, por día hasta 30 y por semana a partir de ahí. Así, un gráfico predeterminado tiene unas pocas decenas de filas independientemente del intervalo, y un mes por horas (721 filas) es algo que se solicita expresamente. since / until aceptan los mismos formatos que en el resto de los casos y, de forma predeterminada, abarcan los últimos 7 días. filters usa los campos de la entidad a la que corresponde la métrica, así que una métrica de spans se filtra por campos de spans.

breakdown divide cada intervalo por tags, name, error_info, error_type, model, provider, span_type, guardrail_name o metadata.<key>. No todas las métricas aceptan todas estas opciones, y siete no aceptan ninguna; la herramienta sabe cuáles son y lo indica antes de llamar al backend, además de mencionar una métrica que responda a la misma pregunta, si existe. Tres familias devuelven varias series a la vez (una duración como p50/p90/p99, una puntuación de comentarios por nombre, uso de tokens por clave), y el backend solo muestra una de ellas a la vez al agrupar, así que series= la selecciona: un percentil, un nombre de puntuación o una clave de uso. Las duraciones usan p50 de forma predeterminada y el uso de tokens, total_tokens; la opción utilizada se repite en la primera línea.

Se omiten los intervalos vacíos y se cuentan debajo, así que un mes tranquilo muestra unas pocas filas en lugar de una columna de ceros, y una tasa en un intervalo sin trazas no aparece en vez de mostrarse como cero.

Consulta schema("list.project_metric") para ver la tabla de métricas, los intervalos y la matriz de agrupación por métrica.

Nombres de un proyecto. score_name enumera los nombres de puntuaciones de comentarios registrados en un proyecto y online_rule los evaluadores de reglas de automatización configurados en él, de donde proceden la mayoría de esos nombres. Ambas son las mismas listas que incluye read("project", …), completas y paginadas, por si la versión limitada de la descripción general no es suficiente.

list(entity_type="score_name", project_name="demo")
list(entity_type="online_rule", project_name="demo")

`write`

Despachador universal de escritura. Pasa operation + data y el despachador valida el contenido, aplica el verbo REST adecuado y devuelve la respuesta del backend.

Operaciones:

Operación	Qué hace
`trace.create`	Registra una traza (o un lote). Es el elemento principal de spans, puntuaciones y comentarios.
`trace.update`	Finaliza o modifica una traza existente.
`span.create`	Registra un span en una traza existente (o un lote).
`score.create`	Adjunta una puntuación numérica de comentarios a una traza, un span o un hilo.
`comment.create`	Adjunta un comentario de texto libre a una traza, un span o un hilo.
`prompt_version.save`	Guarda una nueva versión de un prompt (crea el prompt por nombre si no existe).
`dataset.create`	Crea un conjunto de datos; `type: "test_suite"` lo convierte en un conjunto de pruebas de evaluación.
`dataset_item.upsert`	Inserta o actualiza elementos en un conjunto de datos (siempre con la estructura envolvente).
`experiment.create`	Crea un experimento asociado a un conjunto de datos.
`experiment_item.create`	Adjunta filas de trace + dataset_item a un experimento.
`thread.close`	Cierra un hilo (lo marca como inactivo). Pasa `thread_id` y el proyecto.
`thread.open`	Reabre un hilo cerrado. Pasa `thread_id` y el proyecto.
`agent_insights_job.enable`	Activa Diagnostics para un proyecto (análisis diarios, se puede repetir sin riesgo).
`agent_insights_job.trigger`	Ejecuta ahora un análisis de Diagnostics de las últimas 24 horas.
`agent_insights_issue.resolve`	Marca un problema de Diagnostics como resuelto (pregunta primero al usuario).
`agent_insights_issue.close`	Marca un problema de Diagnostics como no merecedor de acción (pregunta primero al usuario).
`agent_insights_issue.reopen`	Vuelve a incluir en la lista de abiertos un problema de Diagnostics resuelto o cerrado.
`annotation_queue.create`	Crea una cola de anotación de un proyecto, opcionalmente con una vista de anotador personalizada.
`annotation_queue.update`	Modifica una cola de anotación; establece, reemplaza o borra su vista de anotador.

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

`schema`

Inspecciona la estructura JSON exacta y los campos obligatorios de cualquier operación de escritura antes de llamarla; resulta útil si no tienes claro cómo debería ser data. Devuelve el esquema, el ámbito OAuth y un ejemplo validado. Es una consulta pura, sin llamada al backend.

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

La misma herramienta responde list.trace, list.span, list.thread y list.experiment con la referencia de la herramienta list para esa entidad: todos los campos filtrables con su tipo y los operadores válidos, los campos ordenables, si se aplican una ventana temporal y una búsqueda de texto libre, y dos filtros de ejemplo.

schema(operation="list.trace")

Configuración

Estas opciones configuran el servidor local; cada ajuste es una variable de entorno. El servidor alojado en Opik Cloud no acepta ninguna de ellas.

Identidad / endpoint

Variable	Valor predeterminado	Notas
`OPIK_API_KEY`	—	Clave de API para un Comet autohospedado o para Opik Cloud sin el servidor alojado. Opik de código abierto no necesita ninguna, salvo que la implementación añada autenticación.
`OPIK_WORKSPACE`	unset	Nombre del espacio de trabajo. En la nube, con una clave de API, si no se establece se envía `default`, que se resuelve en el espacio de trabajo predeterminado de tu cuenta; establécelo explícitamente si trabajas en otro, o las lecturas procederán silenciosamente del espacio de trabajo equivocado. Déjalo sin establecer con OAuth (el token lo incluye) y en local/OSS (`default` es el único espacio de trabajo allí).
`COMET_WORKSPACE`	—	Alias obsoleto de `OPIK_WORKSPACE` (compatibilidad con versiones anteriores). `OPIK_WORKSPACE` tiene prioridad si ambos están establecidos.
`COMET_WORKSPACE_ID`	unset	UUID opcional del espacio de trabajo. Se incluye en los eventos de analítica cuando se establece y tiene prioridad sobre el valor resuelto. Rara vez se necesita: las instalaciones OAuth obtienen el UUID automáticamente del token.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Establécelo en el host de tu Comet autohospedado o en `https://dev.comet.com` para staging.
`OPIK_URL`	derivado de `COMET_URL_OVERRIDE` + `/opik/api`	Establécelo para Opik de código abierto, que sirve su API en `/api` (`http://localhost:5173/api` localmente). En una plataforma Comet, sobrescríbelo solo si Opik está en un host o una ruta distintos de los de la interfaz de Comet.
`OPIK_DEFAULT_PROJECT_NAME`	unset	Cuando se establece, el bloque `instructions` por sesión indica al LLM que lo pase como `project_name` en cada llamada a una herramienta, salvo que el usuario indique otro proyecto.

Servidor / transporte

Variable	Valor predeterminado	Notas
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` para el inicio desde el host, `streamable-http` para escuchar en un puerto.
`OPIK_MCP_HOST`	`127.0.0.1`	Host de enlace de uvicorn (`streamable-http` únicamente).
`OPIK_MCP_PORT`	`8080`	Puerto de enlace de uvicorn (`streamable-http` únicamente).
`OPIK_MCP_RELOAD`	`false`	`true` para habilitar `--reload` de uvicorn (solo para desarrollo).
`OPIK_MCP_AS_URL`	unset	URL del servidor de autorización OAuth, anunciada en `/.well-known/oauth-protected-resource` (RFC 9728) y utilizada como destino del proxy para las consultas de descubrimiento de AS. Es necesaria para que los hosts MCP inicien el flujo OAuth por HTTP.
`OPIK_MCP_RESOURCE_URI`	unset	URI pública canónica de este servidor, anunciada como `resource` en los metadatos del recurso protegido y utilizada para derivar la indicación `WWW-Authenticate`.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	Cuánto tiempo se confía en una respuesta «válida» de la introspección de tokens de opik-backend antes de que la siguiente solicitud con el mismo token OAuth vuelva a consultar. Limita la carga añadida al backend por la validación en cada solicitud y el intervalo durante el cual se sigue reenviando un token caducado (ese intervalo también termina con el primer 401 que devuelva el backend). El límite lo establece el propio `expires_at` del token cuando el backend informa de uno.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Nivel de registro de stderr.

Cómo elegir un transporte

Dos formatos de bearer, dos contratos para el transporte HTTP. Un token de acceso OAuth opik_mcp_at_… se valida en cada solicitud mediante el endpoint de introspección de tokens de opik-backend (con caché; consulta OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S); un token caducado o revocado recibe un HTTP 401 con WWW-Authenticate: Bearer error="invalid_token", que es lo que los hosts MCP utilizan para activar la concesión silenciosa refresh_token. Una clave de API de Opik no se valida localmente: se reenvía sin modificar a opik-backend, que es el único punto de aplicación de las reglas. Elige el transporte según la forma de implementación:

Escenario	Transporte
Opik Cloud	No hay nada que ejecutar: el servidor alojado es este servidor por HTTP, ejecutado por Comet
Cliente MCP y Opik en la misma máquina (instalación local de OSS)	stdio (recomendado: es lo más sencillo, sin puerto ni configuración de OAuth)
Cliente MCP local → Opik autohospedado	stdio con las variables de entorno de la implementación, o HTTP con OAuth (`OPIK_MCP_AS_URL` apuntando al backend)
opik-mcp servido detrás del mismo perímetro que opik-backend	HTTP: el backend valida los bearer en cada solicitud

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

Telemetría

Variable	Valor predeterminado	Notas
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Establécelo en `false` para desactivar toda la telemetría que no sea de Sentry.
`OPIK_MCP_SENTRY_ENABLED	`true`	Set to `false` para desactivar toda la telemetría de Sentry.
=======

Límites conocidos de los hosts

Los hosts varían en el tiempo que permiten que se ejecute una sola llamada a una herramienta:

Claude Code — no tiene un tiempo de espera documentado para las llamadas a herramientas. Recomendado.
Cursor — tiempo de espera estricto de 60 s que no se reinicia con el progreso (error upstream).
MCP Inspector — MAX_TOTAL_TIMEOUT limita la duración total (60 s de forma predeterminada). Auméntalo en la interfaz de Inspector para operaciones largas.

Si una llamada se queda bloqueada, establece OPIK_MCP_LOG_LEVEL=DEBUG para obtener el registro completo de la solicitud.

Solución de problemas

¿Funciona la configuración? Ejecuta el servidor con el entorno de su configuración de cliente y --check: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Indica el espacio de trabajo y los proyectos que detecta, o qué hay que corregir. Los propios errores del servidor también indican qué cambiar y enlazan a la página de documentación correspondiente.

No se detecta OPIK_API_KEY — la variable no está llegando al proceso del servidor. En Claude Code / Cursor / VS Code, las variables de entorno solo se aplican si están dentro del bloque env de la configuración del servidor MCP, no en tu shell; Codex también reenvía los nombres indicados en env_vars. Inicia una sesión nueva después de editar, ya que los clientes leen la configuración al iniciar una sesión.

Las solicitudes van a /opik/api en una instalación de Opik de código abierto — COMET_URL_OVERRIDE es para una plataforma Comet autohospedada. La versión de código abierto sirve su API en /api: establece OPIK_URL=http://localhost:5173/api (o https://<host>/api) en su lugar. El servidor advierte de esto al iniciarse cuando el host es esta máquina, y --check responde «No Opik API at …».

La llamada de Cursor agota el tiempo de espera a los 60 s — es un error conocido de Cursor, no de opik-mcp. Reduce el alcance de la llamada (un size más pequeño o una ventana más acotada) o ejecuta la misma operación en Claude Code, que no tiene un límite estricto.

El servidor no aparece, no se abre el inicio de sesión, el espacio de trabajo es incorrecto, no se encuentra uvx. Estos casos se tratan en la sección de solución de problemas de la documentación. uvx opik@latest mcp status muestra todos los clientes que tienen configurado el servidor y si su configuración ha cambiado.

Desarrollo

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

Objetivos habituales:

Objetivo	Qué hace
`make install`	`uv sync --locked --extra dev`
`make run`	Ejecuta el servidor MCP (stdio de forma predeterminada).
`make run-dev`	Ejecuta el servidor con el registro DEBUG y `--reload` de uvicorn.
`make dev`	Ejecuta mediante `mcp dev` (envoltorio de modo de desarrollo de Inspector).
`make inspect`	Inicia MCP Inspector contra un servidor en ejecución.
`make test`	`uv run pytest -q`.
`make lint`	`ruff check` + comprobació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, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← migration guide for the deprecated v2 TS server (source: tag `legacy-typescript-final`)
├── pyproject.toml
└── Makefile

Obtener ayuda

Abrir un issue para informar de errores y solicitar funciones
Documentación de Opik para la documentación del SDK y del backend
Slack de la comunidad de Comet para hacer preguntas

Licencia

Apache-2.0.

Comet Opik

¿Qué puedes hacer con Comet Opik MCP?

Documentación

Servidor MCP de Opik

Inicio rápido

Opik Cloud: el servidor alojado

Plugin de Claude Code

Opik autohospedado y de código abierto: el servidor local

Instalar con un agente de programación

Configúralo manualmente (sin comprobación de Opik ni paquete de skills)

Servidor alojado (Opik Cloud)

Claude Code, manualmente

Codex, manualmente

Cursor, manualmente

VS Code Copilot, manualmente

Otros clientes

Opik Cloud con una clave de API

Servidor local (Opik autoalojado y de código abierto)

Claude Code, manualmente

Codex, manualmente

Cursor, manualmente

VS Code Copilot, manualmente

MCP Inspector (pruebas manuales)

¿Vienes de npx opik-mcp?

Herramientas

read

list

write

schema

Configuración

Identidad / endpoint

Servidor / transporte

Cómo elegir un transporte

Telemetría

Límites conocidos de los hosts

Solución de problemas

Desarrollo

Obtener ayuda

Licencia

¿Vienes de `npx opik-mcp`?

`read`

`list`

`write`

`schema`