Comet Opik MCP Server

официальный

Запрашивайте и анализируйте ваши логи Opik, трейсы, промпты и все остальные телеметрические данные от ваших LLM на естественном языке.

GitHub

211

Документация

opik-mcp

Переходите со старого npx opik-mcp? Сервер TypeScript устарел и будет отключён 2026-11-15. Замените npx -y opik-mcp на uvx opik-mcp@latest в конфигурации вашего MCP-клиента. Полное руководство: legacy/typescript/MIGRATION.md.

Сервер Model Context Protocol для Opik + Ollie. Подключите вашего AI-ассистента (Claude Code, Cursor, VS Code Copilot, MCP Inspector) напрямую к вашему рабочему пространству Opik — читайте трейсы, записывайте оценки, сохраняйте версии промптов и задавайте Ollie исследовательские вопросы, и всё это прямо из чата.

Создан для LLM-инженеров, которые уже используют Opik и хотят управлять им из того же AI-ассистента, в котором они пишут код.

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

Установка

opik-mcp — это пакет Python (требуется Python 3.13+). Рекомендуемый способ запуска — uvx, который загружает и запускает последнюю опубликованную версию по требованию — без глобальной установки и манипуляций с virtualenv.

Установите uv один раз:

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

Вам понадобятся две вещи из вашего рабочего пространства Opik:

OPIK_API_KEY — получите его в comet.com/api/my/settings/.
OPIK_WORKSPACE — имя вашего рабочего пространства (в нижнем регистре, как в URL). Например, https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai. Необязательно — по умолчанию используется default (соглашение Opik SDK), что подходит для локальных/OSS-установок; пользователям облака с именованным рабочим пространством следует указать его. COMET_WORKSPACE принимается как устаревший псевдоним.

Примечание о предварительной версии: opik-mcp (Python) ещё не опубликован в PyPI. До выхода первого релиза в PyPI заменяйте uvx opik-mcp в любом фрагменте ниже на: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE необязателен. Опустите строку/ключ OPIK_WORKSPACE в любом фрагменте ниже, и сервер будет использовать рабочее пространство default (подходит для локальных/OSS-установок). Указывайте его только при подключении к именованному облачному рабочему пространству.

Claude Code

Добавьте сервер одной командой:

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

Или отредактируйте ~/.claude.json напрямую:

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

Перезапустите Claude Code. Проверьте с помощью /mcp — opik-mcp должен отображаться как подключённый. Затем в чате спросите: "list my Opik projects" — Claude вызовет инструмент list, и вы увидите проекты вашего рабочего пространства.

Cursor

Отредактируйте ~/.cursor/mcp.json (глобально) или .cursor/mcp.json (для проекта) или откройте Cmd+Shift+J → Features → Model Context Protocol:

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

Перезагрузите Cursor; зелёная точка рядом с opik-mcp на панели MCP подтверждает подключение. Спросите в чате: "list my Opik projects".

Тайм-аут Cursor 60 секунд. Cursor применяет жёсткий тайм-аут вызова инструмента, который не сбрасывается при уведомлениях о прогрессе. Длительные операции ask_ollie будут завершаться ошибкой в Cursor. См. Известные ограничения хостов.

VS Code Copilot

.vscode/mcp.json в вашем рабочем пространстве (или в User Settings JSON):

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

Перезагрузите окно; индикатор MCP в Copilot Chat покажет opik-mcp, как только сервер станет доступен. Спросите в чате: "list my Opik projects".

MCP Inspector (ручное тестирование)

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

Self-hosted Opik

Добавьте COMET_URL_OVERRIDE (и OPIK_URL, если Opik находится по нестандартному пути) в тот же блок env в конфигурации вашего хоста:

{
  "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 и run_experiment доступны только в Comet Cloud — на self-hosted эти вызовы будут завершаться ошибкой при отправке, поэтому используйте read / list / write напрямую. Установка OPIK_MCP_ANALYTICS_SOURCE="" исключает вашу установку из метки источника cloud-Comet в событиях телеметрии.

Инструменты

opik-mcp предоставляет небольшой, ориентированный на результат набор — шесть инструментов, охватывающих полный жизненный цикл (чтение → аннотирование → курирование → создание → итерация).

Инструмент	Назначение
`read`	Универсальное чтение по id / имени / URI `opik://`
`list`	Универсальный список с опциональным фильтром по имени + пагинация
`ask_ollie`	Исследование / синтез через встроенного ассистента Opik
`write`	Универсальная запись — запись трейсов/спанов, оценка, комментарий, сохранение промптов, управление тестовыми наборами и экспериментами
`schema`	Интроспекция схем операций записи (используется LLM для построения корректных полезных нагрузок)
`run_experiment`	Запуск оценочного эксперимента от начала до конца через Ollie

`read`

Один инструмент для любого вопроса «покажи мне X». Принимает entity_type плюс id (UUID или, для именуемых типов, имя) или полный URI opik://. Составные чтения (trace, prompt) встраивают свои дочерние элементы, так что один вызов возвращает полную картину.

Поддерживаемые сущности: project, trace, span, test_suite, experiment, prompt. Поиск по имени доступен для project, experiment, prompt, test_suite (медленнее — два вызова API — и может вернуть несколько совпадений).

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

`list`

Просмотр коллекции с опциональным фильтром по имени и пагинацией. Типы, привязанные к проекту (trace, test_suite_item, prompt_version), требуют UUID родительского элемента.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

Для исследовательских вопросов, синтеза между сущностями или всего, что требует экспертизы в предметной области Opik. Ollie имеет прямой доступ на чтение к вашему рабочему пространству и может выполнять записи (оценки, комментарии, элементы тестовых наборов, версии промптов) в процессе работы, когда его попросят.

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

Возвращает финальный текст ассистента плюс thread_id. Передавайте его при последующих запросах, чтобы сохранить контекст — у Ollie нет памяти между тредами.

Режим YOLO (по умолчанию). Записи, которые Ollie выполняет в процессе работы, выполняются без подтверждения каждого действия. Каждое авто-одобрение записывается как строка аудита JSON в логгер Python opik_mcp.audit. Чтобы вместо этого требовать подтверждения, установите OPIK_MCP_AUTO_APPROVE=disabled — тогда запросы подтверждения Ollie будут отображаться как типизированные ошибки, которые вы можете повторно выполнить вручную.

Доступно только в Comet Cloud.

`write`

Универсальный диспетчер записи. Передайте operation + data, и диспетчер проверит полезную нагрузку, применит правильный REST-метод и вернёт ответ бэкенда.

Операции:

Операция	Что делает
`trace.create`	Записать один трейс (или пакет). Родитель для спанов / оценок / комментариев.
`trace.update`	Завершить или изменить существующий трейс.
`span.create`	Записать спан в существующий трейс (или пакет).
`score.create`	Прикрепить числовую оценку обратной связи к трейсу, спану или треду.
`comment.create`	Прикрепить текстовый комментарий к трейсу, спану или треду.
`prompt_version.save`	Сохранить новую версию промпта (создаёт промпт по имени, если отсутствует).
`test_suite.create`	Создать оценочный тестовый набор.
`test_suite_item.upsert`	Вставить или обновить элементы в тестовом наборе (всегда в форме конверта).
`experiment.create`	Создать эксперимент, привязанный к тестовому набору.
`experiment_item.create`	Прикрепить строки трейса + dataset_item к эксперименту.

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

`schema`

Проверьте точную JSON-схему и обязательные поля любой операции записи перед её вызовом — полезно, когда вы не уверены, как должен выглядеть data. Возвращает схему, область OAuth и один проверенный пример. Чистый поиск, без вызова бэкенда.

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

`run_experiment`

Запустить оценочный эксперимент от начала до конца через Ollie. Принимает один словарь experiment_config, который отражает форму эксперимента Opik (промпт, тестовый набор, оценщики); Ollie выполняет запуск и записывает результаты обратно как эксперимент Opik.

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

Доступно только в Comet Cloud.

Конфигурация

Каждый параметр — это переменная окружения. Обязательные выделены жирным.

Идентификация / конечная точка

Переменная	По умолчанию	Примечания
`OPIK_API_KEY`	—	Обязательна для `ask_ollie` и любого аутентифицированного чтения/записи.
`OPIK_WORKSPACE`	`default`	Имя рабочего пространства. Необязательно — по умолчанию используется `default` (соглашение Opik SDK). Пользователям облака с именованным рабочим пространством следует указать его.
`COMET_WORKSPACE`	—	Устаревший псевдоним для `OPIK_WORKSPACE` (обратная совместимость). `OPIK_WORKSPACE` имеет приоритет, если заданы оба.
`COMET_WORKSPACE_ID`	—	Необязательный UUID рабочего пространства. Включается в события аналитики, если задан, чтобы BI мог выполнять соединение по стабильному идентификатору, а не по (изменяемому) имени рабочего пространства.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Укажите ваш self-hosted хост Comet или `https://dev.comet.com` для staging.
`OPIK_URL`	выводится из `COMET_URL_OVERRIDE` + `/opik/api`	Переопределите, только если Opik находится на другом хосте/пути, отличном от интерфейса Comet.
`OPIK_DEFAULT_PROJECT_NAME`	не задано	Если задано, блок `instructions` для каждой сессии предписывает LLM передавать это как `project_name` при каждом вызове инструмента, если пользователь не укажет другой проект.

Сервер / транспорт

Переменная	По умолчанию	Примечания
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` для запуска хостом, `streamable-http` для прослушивания порта.
`OPIK_MCP_HOST`	`127.0.0.1`	Хост привязки uvicorn (только `streamable-http`).
`OPIK_MCP_PORT`	`8080`	Порт привязки uvicorn (только `streamable-http`).
`OPIK_MCP_RELOAD`	`false`	`true` для включения `--reload` uvicorn (только для разработки).
`OPIK_MCP_AS_URL`	не задано	URL сервера авторизации OAuth, объявляемый в `/.well-known/oauth-protected-resource` (RFC 9728) и используемый в качестве целевого прокси для зондов AS-discovery. Требуется для начальной загрузки MCP-хостами процесса OAuth по HTTP.
`OPIK_MCP_RESOURCE_URI`	не задано	Канонический публичный URI этого сервера, объявляемый как `resource` в метаданных защищённого ресурса и используемый для получения подсказки `WWW-Authenticate`.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Порог логирования stderr.

Выбор транспорта

opik-mcp не выполняет локальную проверку учётных данных при HTTP-транспорте: любой корректно сформированный Authorization: Bearer … (ключ API Opik или токен доступа OAuth opik_mcp_at_…) пересылается без изменений в opik-backend, который является единственной точкой обеспечения аутентификации. Выбирайте транспорт в зависимости от схемы развёртывания:

Сценарий	Транспорт
MCP-клиент и Opik на одной машине (локальная OSS-установка)	stdio (рекомендуется — самый простой, без портов, без настройки OAuth)
Локальный MCP-клиент → удалённый Opik (Comet cloud / self-hosted)	stdio с `OPIK_API_KEY` или HTTP с OAuth (`OPIK_MCP_AS_URL` указывает на бэкенд)
Размещённый opik-mcp за тем же шлюзом, что и opik-backend	HTTP — токены проверяются бэкендом при каждом запросе

Примечание для локальных OSS-установок: OSS-бэкенд не аутентифицирует запросы, поэтому HTTP opik-mcp перед ним так же открыт, как и сам OSS REST API. Используйте привязку по умолчанию 127.0.0.1 (и предпочитайте stdio) в общих сетях.

Ollie / длительные вызовы

Переменная	По умолчанию	Примечания
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` для требования подтверждения каждого действия перед выполнением записей Ollie в процессе работы. На хостах, поддерживающих возможность MCP `elicitation`, пользователь видит запрос да/нет; на более простых хостах запрос отображается как типизированная ошибка, которую можно повторно выполнить вручную.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Как долго запрос подтверждения Ollie в процессе работы может ожидать пользователя, прежде чем будет считаться отменённым. `0` отключает ограничение (только для отладки).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Предел опроса холодного старта пода Ollie.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Интервал опроса холодного старта.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	Периодичность сторожевого таймера — отправляет тик `notifications/progress`, когда под молчит, предотвращая тайм-ауты хоста.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Жёсткий предел молчания пода, после которого `ask_ollie` прерывается. `0` отключает (только для отладки).

Телеметрия

Анонимные события использования (только тип события + время — без содержимого запросов). Включается SHA-256 дайджест вашего ключа API, чтобы поддержка могла найти вашу учётную запись; исходный ключ никогда не покидает процесс. Отказ: OPIK_MCP_ANALYTICS_ENABLED=false.

Переменная	По умолчанию	Примечания
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Установите в `false`, чтобы отключить всю телеметрию.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Переопределение для staging.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Тег на каждом событии (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Получатель использует это для пометки `on_prem=False`. При локальных установках следует переопределить на `""` или собственный домен.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	Тайм-аут HTTP-соединения.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	Общий тайм-аут HTTP-запроса.

Известные ограничения хостов

Спецификация MCP позволяет хостам сбрасывать тайм-аут вызова инструмента при notifications/progress — opik-mcp генерирует одно событие на каждое SSE-событие Ollie плюс 15-секундный сторожевой heartbeat. Реальность неоднородна:

Claude Code — документированного тайм-аута вызова инструмента нет; heartbeat поддерживает вызов активным до message_end. Рекомендуется.
Cursor — жесткий тайм-аут 60 с, который не сбрасывается при прогрессе (известная ошибка). Длительные запуски Ollie будут завершаться ошибкой. Делайте запросы ask_ollie сфокусированными.
MCP Inspector — MAX_TOTAL_TIMEOUT ограничивает общую продолжительность (по умолчанию 60 с). Увеличьте его в интерфейсе Inspector для длительных операций.

Если вызов зависает, установите OPIK_MCP_LOG_LEVEL=DEBUG — сбои heartbeat (обычно отключения хоста) регистрируются на opik_mcp.ask_ollie на уровне отладки.

Устранение неполадок

OPIK_API_KEY is required to use ask_ollie — переменная не доходит до серверного процесса. В Claude Code / Cursor / VS Code переменные окружения применяются только внутри блока env конфигурации MCP-сервера, а не в вашей оболочке. Перезапустите хост после редактирования.

ask_ollie возвращает "pod not ready" через 2 минуты — холодный старт пода Ollie превысил OPIK_MCP_POD_READY_TIMEOUT_S. Повторите попытку — второй вызов обычно попадает на прогретый под.

ask_ollie / run_experiment завершается ошибкой диспетчеризации на self-hosted Opik — эти инструменты доступны только в Comet Cloud. Используйте read / list / write напрямую на self-hosted.

Вызов в Cursor завершается по тайм-ауту через 60 с — известная ошибка Cursor, не opik-mcp. Либо сократите запрос Ollie, либо выполните ту же операцию в Claude Code, где нет жесткого ограничения.

Разработка

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

Основные цели:

Цель	Что делает
`make install`	`uv sync --extra dev`
`make run`	Запуск MCP-сервера (по умолчанию stdio).
`make run-dev`	Запуск с DEBUG-логированием + uvicorn `--reload`.
`make dev`	Запуск через `mcp dev` (обертка режима разработки Inspector).
`make inspect`	Запуск MCP Inspector для работающего сервера.
`make test`	`uv run pytest -q`.
`make test-live`	Живое сквозное тестирование с `dev.comet.com` (установите `OPIK_API_KEY` + `OPIK_WORKSPACE`).
`make lint`	`ruff check` + проверка форматирования.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Структура репозитория:

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

Получить помощь

Создать issue для сообщений об ошибках и запросов функций
Документация Opik по SDK / бэкенду
Comet community Slack для вопросов

Переходите с v2? Устаревший TypeScript-сервер по-прежнему поставляется в npm как opik-mcp@^2 (npx -y opik-mcp); исходный код сохранен в legacy/typescript/. См. legacy/typescript/DEPRECATED.md для политики поддержки.

Лицензия

Apache-2.0.