Comet Opik

официальный

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

GitHub

226

Что можно делать с Comet Opik MCP?

Запрос трассировок по проекту — Узнайте, какие трассировки в проекте завершились ошибкой сегодня, с фильтрами по информации об ошибках, длительности или использованию токенов.
Чтение любой сущности Opik — Получите проект, трассировку, спан, датасет, эксперимент, промпт, тред или проблему Diagnostics по id, имени или URI opik://.
Запись оценок и комментариев — Оцените трассировку по метрике обратной связи с указанием причины или добавьте комментарии с помощью инструмента записи.
Сохранение версий промптов — Создавайте и сохраняйте новые версии промптов вместе с датасетами и экспериментами.
Проверка схем записи — Запросите схему операции записи, чтобы сформировать корректную полезную нагрузку перед отправкой.
Проверка состояния проекта — Прочитайте данные проекта, чтобы узнать количество трассировок, частоту ошибок, среднюю длительность и общую стоимость за последние 7 дней.

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

MCP-сервер Opik

Официальный сервер Model Context Protocol (MCP) для Opik — платформы с открытым исходным кодом для наблюдаемости и оценки LLM, созданной Comet. Подключите свой AI-хост (Claude Code, Cursor, VS Code Copilot, Codex, opencode или любой MCP-клиент) напрямую к рабочей области Opik: просматривайте трассировки, записывайте оценки и сохраняйте версии промптов — всё прямо из чата.

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

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

Быстрый старт

Одна команда настраивает Opik в AI-клиентах на вашем компьютере, включая Claude Code. Она находит ваш Opik (сохранённый в ~/.opik.config, запущенный на localhost или выбранный вами), регистрирует MCP-сервер, устанавливает набор навыков Opik и проверяет подключение. В Opik Cloud не нужно работать с API-ключом: клиент выполняет вход в браузере. Нужен uv и не нужен SDK Opik:

uvx opik@latest mcp configure

Если вы запускаете команду не из терминала, например из агента для написания кода или скрипта, укажите клиент:

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

--ai-client также принимает codex, cursor, vscode и opencode. При таком запуске команда использует Opik, сохранённый в ~/.opik.config, включая API-ключ, или Opik, отвечающий на localhost. Если ни один вариант не подходит, команда останавливается и запрашивает --deployment.

Агенту для написания кода, которому поручили «install opik mcp», полные инструкции, включая вопросы пользователю, доступны в uvx opik-mcp@latest --help. Они совпадают с разделом Установка с помощью агента для написания кода ниже.

При ручной регистрации сервера с помощью команд для клиентов из раздела Настройка вручную пропускаются проверка используемого Opik и установка набора навыков, поэтому этот способ предназначен для клиентов, которые не поддерживаются установщиком.

Ваш Opik	Сервер	Транспорт	Вход
Opik Cloud (`www.comet.com`)	размещённый сервер, управляемый Comet	Streamable HTTP	в браузере (OAuth); API-ключ не нужен
Comet с самостоятельным размещением, Opik с открытым исходным кодом	локальный сервер, этот пакет	stdio	переменные среды; API-ключ нужен только там, где этого требует развёртывание

Клиенты загружают MCP-серверы при запуске сеанса, поэтому после настройки начните новый сеанс.

Руководство по настройке, устранению неполадок и часто задаваемые вопросы: comet.com/docs/opik/mcp-server.

Opik Cloud: размещённый сервер

Comet запускает сервер по адресу https://www.comet.com/opik/api/v1/mcp. Клиент подключается по HTTP и при первом подключении открывает браузер для входа. Ничего устанавливать не нужно, API-ключ не нужен, рабочую область задавать не нужно: сервер работает в рабочей области, которую вы выберете при входе. После добавления сервера начните новый сеанс и спросите: «list my Opik projects».

Команда из раздела Быстрый старт настраивает сервер для Claude Code, Codex, Cursor, VS Code Copilot и opencode, а также устанавливает набор навыков. В Claude Code то же самое можно сделать одной командой с помощью плагина. Кнопки ниже добавляют сервер в Cursor или VS Code одним щелчком; другие способы ручной регистрации описаны в разделе Настройка вручную.

Плагин Claude Code

Плагин opik устанавливает навыки Opik и регистрирует размещённый MCP-сервер для Opik Cloud:

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

В Claude Code версии ниже 2.1.275 выполните /plugin marketplace add comet-ml/opik-mcp, затем /plugin install opik@opik. Навыки загружаются как opik:<skill>, например opik:opik-instrument, а /mcp показывает сервер как plugin:opik:opik-cloud. Это сервер Opik Cloud. Начните новый сеанс, затем войдите через /mcp → Authenticate. Для Comet с самостоятельным размещением, где запущен MCP OAuth-сервер, добавьте его с помощью claude mcp add --transport http opik-mcp https://<host>/opik/api/v1/mcp; для любого другого Opik с самостоятельным размещением или с открытым исходным кодом используйте команду из раздела Быстрый старт. Затем отключите plugin:opik:opik-cloud в /mcp. Claude Code не обновляет плагин из этого маркетплейса автоматически: выполните /plugin marketplace update opik, затем /plugin update opik@opik или включите автообновление маркетплейса в /plugin. Этот маркетплейс предоставляет main, версия которого может быть новее последнего релиза. Обновление появляется только при изменении версии плагина, то есть с каждым релизом.

Если вы ранее добавили opik-mcp с тем же URL, Claude Code сохранит вашу копию и не установит копию плагина. Если у вас другой сервер, например локальный uvx opik-mcp, загрузятся оба: выполните claude mcp remove opik-mcp, чтобы оставить только сервер плагина. Навыки из набора навыков также загружаются вместе с копиями плагина; удалите их с помощью npx skills remove --global --agent claude-code, где можно выбрать, какие именно удалить.

Opik с самостоятельным размещением и Opik с открытым исходным кодом: локальный сервер

opik-mcp запускается на вашем компьютере: клиент запускает его с помощью uvx opik-mcp и обменивается с ним данными через stdio. Команда из раздела Быстрый старт настраивает сервер на основе вашего ~/.opik.config или локального Opik; для ручной регистрации см. раздел Настройка вручную. Установите uv один раз; при первом запуске он загрузит пакет и, если потребуется, Python 3.13:

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

uvx opik-mcp использует сохранённую uv копию пакета, поэтому запускается быстро; uv cache clean opik-mcp заставляет при следующем запуске загрузить последнюю версию. uvx opik-mcp@latest обращается к PyPI при каждом запуске, что добавляет примерно полторы секунды. Codex ждёт mcp_optional_startup_grace_ms (по умолчанию 1 s) ответа серверов перед созданием первого списка инструментов, поэтому медленный запуск может привести к тому, что инструменты не попадут в первый ход. Одноразовые команды в этом README (opik mcp configure, opik mcp status, --help, --check) содержат @latest, поэтому никогда не запускают копию, сохранённую uv несколько месяцев назад.

Переменные среды указывают серверу, где находится ваш Opik:

Ваш Opik	Переменные среды
Opik с открытым исходным кодом на этом компьютере	`OPIK_URL=http://localhost:5173/api`
Opik с открытым исходным кодом на сервере	`OPIK_URL=https://<host>/api`, а также `OPIK_API_KEY` только если в развёртывании включена аутентификация
Платформа Comet с самостоятельным размещением (интерфейс Opik доступен по адресу `https://<host>/opik`)	`COMET_URL_OVERRIDE=https://<host>`, `OPIK_WORKSPACE`, `OPIK_API_KEY`

Opik с открытым исходным кодом предоставляет API по адресу /api и использует одну рабочую область — default, поэтому OPIK_WORKSPACE не требуется. COMET_URL_OVERRIDE указывал бы серверу на /opik/api, который Opik с открытым исходным кодом не предоставляет.
В Comet с самостоятельным размещением есть именованные рабочие области. Задайте OPIK_WORKSPACE равным сегменту после /opik/ в URL Opik; если не указать его, данные будут считываться из рабочей области по умолчанию для вашей учётной записи, без сообщения об ошибке.
В Comet с самостоятельным размещением, где запущен MCP OAuth-сервер (по умолчанию отключён), вместо этого можно использовать размещённый сценарий по адресу https://<host>/opik/api/v1/mcp.
Подставьте все значения. Сервер отклоняет фиктивные названия рабочих областей, например <your-workspace> или ${input:OPIK_WORKSPACE}; фиктивный URL отправляется как есть, и подключиться не удаётся.
OPIK_MCP_ANALYTICS_SOURCE="" в блоке env отключает для установки с самостоятельным размещением метку источника cloud-Comet в событиях телеметрии.

Прежде чем добавлять сервер в клиент, проверьте настройки: запустите его с теми же переменными среды и --check. Он выполнит один запрос к Opik и выведет рабочую область и количество обнаруженных проектов либо укажет, что нужно исправить, со ссылкой на документацию, а затем завершится с кодом 0 или 1. Клиент не может сообщить об этом до начала нового сеанса: Claude Code показывает Connected даже при неверном ключе, а Codex ничего не запускает до этого момента.

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

Затем зарегистрируйте сервер в клиенте: локальный сервер, вручную.

Установка с помощью агента для написания кода

Для AI-агента, которому поручили установить сервер, например «install opik mcp». Цель — зарегистрировать сервер для Opik пользователя, установить набор навыков Opik и выполнить вход пользователя. Определите, какой Opik используется на этом компьютере, и спрашивайте пользователя только о том, чего нельзя определить самостоятельно: один вопрос в сообщении, дождитесь ответа, прежде чем задавать следующий. Установщик на шаге 3 выполняет всю настройку за один запуск, поэтому сначала завершите шаги 1 и 2. uvx opik-mcp@latest --help выводит эти шаги.

Проверьте, что уже настроено.
```
uvx opik@latest mcp status
```
Команда показывает Opik, сохранённый в ~/.opik.config (URL и рабочую область, но не ключ), а также клиентов, в которых сервер уже зарегистрирован. В Claude Code дополнительно выполните claude mcp list: команда показывает коннекторы claude.ai и записи под другими именами. Она также выводит команду для каждой записи; в старой записи npx может быть API-ключ — не повторяйте его.
- Сервер для https://www.comet.com/opik/api/v1/mcp под любым именем, например коннектор claude.ai, означает, что он уже зарегистрирован: не добавляйте второй. Установите только набор навыков с помощью npx skills add comet-ml/opik-skills -g --all. Если сервер отображается как ! Needs authentication, перейдите к шагу 4.
- Установщик без запроса заменяет существующую запись opik-mcp, например запись для старого сервера npx. Спросите пользователя, прежде чем запускать его.
Определите, какой Opik использует пользователь.
- Сохранён в ~/.opik.config: используйте его и сообщите пользователю, какой Opik настраиваете. Установщик считывает его, включая API-ключ, поэтому запрашивать ключ не нужно.
- Нет ~/.opik.config: curl -s http://localhost:5173/api/is-alive/ping. Ответ означает, что на этом компьютере запущен Opik с открытым исходным кодом. В изолированной оболочке, например в Codex, отсутствие ответа может означать, что у оболочки нет доступа к сети, а не то, что Opik отсутствует.
- Ни один вариант не подходит: спросите пользователя и не выбирайте самостоятельно. URL Opik в проекте, например OPIK_URL_OVERRIDE в .env, позволяет задать вопрос с ответом «да» или «нет». В противном случае спросите: «Какой Opik вы используете: Opik Cloud (www.comet.com), Opik с открытым исходным кодом (его URL) или платформу Comet с самостоятельным размещением (её URL и рабочую область)?»

Запустите установщик для клиента, в котором вы работаете. Он устанавливает набор навыков Opik вместе с сервером, с --skills или без него; сохраните флаг в команде, которую предложите пользователю запустить позже. Для Opik Cloud установщик открывает браузер для входа и ждёт минуту, поэтому сначала предупредите пользователя.

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

--ai-client также принимает codex, cursor, vscode и opencode. Если Opik сохранён в ~/.opik.config или запущен на localhost, запустите команду без изменений: --deployment временно убирает сохранённую конфигурацию, включая API-ключ. Если ни один вариант не подходит, добавьте флаг для Opik, который пользователь назвал на шаге 2:

Opik пользователя	Добавьте
Opik Cloud, `www.comet.com`	`--deployment cloud`
Opik с открытым исходным кодом	`--deployment local`, а также `--url <url>`, если он запущен не на localhost
Платформа Comet с самостоятельным размещением, `/opik/` в её URL	`--deployment self-hosted --url <url> --workspace <workspace>`, указав `OPIK_API_KEY` в оболочке

Если команда завершилась с ошибкой, например потому что Opik не отвечает, сообщите пользователю, что она вывела и что нужно проверить, например VPN или URL. Не переключайтесь на другой Opik.

Вход в Opik Cloud. Если установщик сообщает, что вход на сервер ещё не выполнен, предложите пользователю запустить claude mcp login opik-mcp или /mcp в сеансе Claude Code, а не запускайте команду сами: она ждёт завершения входа в браузере. В коннекторе claude.ai вход выполняется через /mcp. При входе нужно выбрать рабочую область; если в ~/.opik.config сохранена рабочая область, укажите её.
Завершите настройку. Сообщите, что установлено и что осталось сделать. Назовите набор навыков: навыки Opik, установленные для каждого проекта; они учат агента инструментировать, оценивать и отлаживать приложения с помощью Opik. Клиенты загружают MCP-серверы и навыки при запуске сеанса: попросите пользователя начать новый сеанс, а затем попробовать «list my Opik projects».

Для всех вариантов:

Не просите пользователя вставлять API-ключ в чат. Размещённому серверу ключ не нужен; в остальных случаях возьмите его из среды оболочки ("$OPIK_API_KEY") или предложите пользователю запустить команду.
Не угадывайте рабочую область. Это сегмент после comet.com/opik/ (или /opik/ в Comet с самостоятельным размещением) в URL Opik пользователя.
Не выводите ~/.claude.json или ~/.opik.config: оба могут содержать API-ключи. uvx opik@latest mcp status и claude mcp list показывают нужные сведения, а установщик сам считывает конфигурацию.
Если проверка разрешений блокирует команду, не обходите её. Предложите пользователю запустить команду самостоятельно (в Claude Code перед запуском из запроса выполните !). Для клиента, который установщик не знает, зарегистрируйте сервер вручную с помощью команд из раздела Настройка вручную: размещённый сервер для Opik Cloud, локальный сервер для остальных.
Перед регистрацией локального сервера запустите его с окружением, которое будете передавать, и --check, экспортировав OPIK_API_KEY в оболочке, а не указывая его в команде: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Процесс завершится с кодом 0 и укажет рабочую область, которую он видит, либо сообщит, что нужно исправить. После регистрации Claude Code сообщает Connected даже при неверном ключе, а Codex ничего не проверяет.
Claude Code отказывается добавлять запись opik-mcp, если она уже существует, поэтому сначала удалите её с помощью claude mcp remove opik-mcp --scope user; команда Codex add заменяет её.
После регистрации в Claude Code прочитайте только строку состояния: claude mcp get opik-mcp | grep Status. Полный вывод содержит блок env, включая ключ API. Размещённый сервер показывает ! Needs authentication, пока не выполнена команда claude mcp login opik-mcp. В Codex нет команды, которая запускает сервер до начала сеанса; codex mcp get opik-mcp показывает сохранённые данные, скрывая значения переменных окружения.

Настройка вручную (без проверки Opik и набора навыков)

Команда Быстрый старт выполняет всё это для Claude Code, Codex, Cursor, VS Code Copilot и opencode, а также проверяет, какой вариант Opik вы используете, и устанавливает набор навыков. Регистрируйте сервер вручную только для другого клиента или чтобы посмотреть, что записывает установщик. Если кодирующий агент устанавливает его для пользователя, запустите установщик: см. раздел Установка с помощью кодирующего агента.

Размещённый сервер (Opik Cloud)

Claude Code, вручную

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

Затем войдите в систему через /mcp → Authenticate в сеансе Claude Code. Откроется браузер, поэтому вход выполняет человек за клавиатурой; в собственном терминале то же самое делает команда claude mcp login opik-mcp. Команда --scope user делает сервер доступным во всех проектах; без неё Claude Code регистрирует его только для текущего каталога. При подключении по SSH команда claude mcp login opik-mcp --no-browser выводит URL для входа, который нужно открыть на своём компьютере; последний шаг требует интерактивного терминала (ssh -t).

Codex, вручную

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

Команда add открывает страницу входа; codex mcp login opik-mcp открывает её снова. В ~/.codex/config.toml тот же сервер задаётся так:

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

Cursor, вручную

Используйте кнопку под разделом размещённый сервер или добавьте запись в ~/.cursor/mcp.json:

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

VS Code Copilot, вручную

Используйте кнопку под разделом размещённый сервер или добавьте запись в .vscode/mcp.json в рабочей области либо в пользовательский mcp.json (MCP: Open User Configuration):

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

Другие клиенты

Любой клиент, принимающий URL, может использовать размещённый сервер:

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

Клиент, который умеет запускать только локальные команды, может подключиться к нему через npx -y mcp-remote https://www.comet.com/opik/api/v1/mcp.

Opik Cloud с ключом API

Если никто не может выполнить вход через браузер, например агент запускается без присмотра из скрипта или клиент не поддерживает MCP OAuth, используйте ключ API из comet.com/api/my/settings/ вместо этого, направив локальный сервер на Opik Cloud:

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

В блоке env других клиентов указываются те же две переменные. Задайте OPIK_WORKSPACE равным сегменту после comet.com/opik/ в URL Opik (https://www.comet.com/opik/acme-ai/projects → acme-ai). Если не указать это значение, сервер отправит default, который Comet сопоставит с рабочей областью по умолчанию вашей учётной записи. В результате данные могут считываться не из той рабочей области, и ошибки не будет.

Локальный сервер (Opik с самостоятельным размещением и с открытым исходным кодом)

В примерах используется локальный Opik с открытым исходным кодом. Для Comet с самостоятельным размещением замените три переменные значениями из таблицы. После добавления сервера начните новый сеанс и спросите: «list my Opik projects».

Claude Code, вручную

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

Для Comet с самостоятельным размещением, если ключ находится в переменной оболочки OPIK_API_KEY:

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

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

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

Команда claude mcp get opik-mcp показывает ✔ Connected после запуска сервера. Это не подтверждает правильность URL или ключа, поскольку до Opik доходит только вызов инструмента; это делает --check (локальный сервер). Она также выводит блок env, включая ключ API.

Codex, вручную

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

Или отредактируйте ~/.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 передаёт только переменные из env и имена из env_vars, поэтому экспортированный в оболочке ключ иначе до него не дойдёт.

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_URL": "http://localhost:5173/api"
      }
    }
  }
}

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

VS Code Copilot, вручную

Добавьте запись в .vscode/mcp.json в рабочей области или в пользовательский mcp.json (MCP: Open User Configuration):

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

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

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

Переходите с `npx opik-mcp`?

Сервер TypeScript (npm opik-mcp@2) объявлен устаревшим и перестанет обрабатывать запросы 2026-11-15. Для новой установки запустите команду Быстрый старт; uvx opik-mcp — это команда, которую клиент запускает для старта сервера, а не установщик. Чтобы перенести существующую конфигурацию Opik Cloud, переключитесь на размещённый сервер и удалите ключ API. В противном случае в конфигурации MCP-клиента замените npx -y opik-mcp на uvx opik-mcp. Некоторые переменные окружения переименованы, а флаги командной строки больше не считываются: см. руководство по миграции. Политика поддержки: DEPRECATED.md. Исходный код TypeScript находится в теге git legacy-typescript-final.

Инструменты

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

Инструмент	Назначение
`read`	Универсальное чтение по идентификатору / имени / URI `opik://`
`list`	Универсальный список с необязательным фильтром по имени и постраничной выдачей
`write`	Универсальная запись — журналирование трассировок/спанов, оценка, комментарии, сохранение промптов, управление наборами данных и экспериментами
`schema`	Просмотр схем операций записи (используются LLM для формирования допустимых полезных нагрузок)
`read_skill`	Чтение одного из навыков Opik для агентов, включённых в этот сервер

`read`

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

Указанная запись возвращается целиком. Дочерние элементы, включённые в ответ, — нет: их содержимое получается через truncate=true бэкенда, поэтому поле размером более ~10 КБ обрезается в ClickHouse, а изображения в base64 заменяются на "[image]". Иначе одно и то же вложение, повторённое в 200 спанах, обошлось бы дороже всего остального в ответе. Об этом сообщается в spanBodies / messageBodies, а любой дочерний элемент можно получить целиком отдельно через его собственный read("span", id) или read("trace", trace_id), которые обращаются к конечным точкам, вообще не имеющим параметра truncate.

Длина включённой коллекции также ограничена: 200 спанов, 200 ходов, 100 версий промпта. Если элементов больше, spansTruncated / messagesTruncated / versionsTruncated получает значение true, а расположенная рядом строка moreSpans / moreMessages / moreVersions содержит количество и точный вызов list(...), который продолжает выдачу с места, на котором остановилась включённая часть.

Поддерживаемые сущности: project, trace, span, dataset, dataset_item, experiment, prompt, thread, agent_insights_issue. Поиск по имени доступен для project, experiment, prompt, dataset (медленнее — два вызова API — и может вернуть несколько совпадений). thread и agent_insights_issue относятся к проекту: передайте project_id или project_name либо ссылку/URI, содержащую проект. Раньше dataset и dataset_item назывались test_suite и test_suite_item; старые имена по-прежнему работают, но не рекомендуются, и в новом коде следует использовать новые.

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

Ссылка, скопированная из интерфейса Opik, подходит в качестве id: ссылка на поток или страницу Diagnostics содержит проект, поэтому project_id не требуется, а тип сущности определяется по ссылке.

Чтение project за один вызов отвечает на вопрос «как обстоят дела в моём проекте». Оно возвращает {project, summary, vocabulary, contains, url}: запись, а затем четыре показателя, которые страница Logs отображает в виде карточек (количество трассировок, доля ошибок, средняя длительность, общая стоимость) за последние 7 дней в сравнении с предыдущими 7 днями; только трафик SDK, как на экране. Параметры since / until сдвигают это окно; since="30d" — значение, которое открывается в интерфейсе. Если за период нет трассировок, доля или среднее возвращаются как null, поскольку 0% ошибок за неделю без трафика выглядит как хорошая неделя.

vocabulary — это карта, необходимая перед любыми другими запросами: названия оценок обратной связи проекта, ключи использования токенов и правила автоматизации, оценивающие его трассировки. Именно эти названия нужно указывать в фильтре или в series= ниже; если угадать их неправильно, вернётся пустая страница, похожая на хорошие новости. Количество оценок и правил ограничено, но всегда указывается общее число и вызов для получения остальных; ключи использования перечисляются полностью, поскольку больше нигде их нельзя получить. contains указывает самый свежий эксперимент, набор данных, версию промпта и запуск оптимизации, поэтому для ответа на вопрос «что здесь происходило» не нужны ещё четыре вызова. Если загрузить какую-либо часть не удалось, об этом сообщается, а не создаётся впечатление, что она пуста; пустые части не включаются.

Чтение agent_insights_issue возвращает {issue, example_trace_ids, details}: запись проблемы Diagnostics (название, описание, причина, предлагаемое исправление, важность, статус), дедуплицированные идентификаторы трассировок, в которых она проявляется (та же выборка, что и на странице Diagnostics — откройте одну с помощью read("trace", id)), и разбивку по дням. Содержимое трассировок не включается, поэтому чтение требует всего одного вызова бэкенда. Параметры since / until сужают диапазон строк по дням; по умолчанию берутся все данные за всё время. Если сервер знает URL Opik и рабочую область сеанса, чтение также содержит url (страницу Diagnostics этой проблемы) и trace_url_template (глубокую ссылку на любую из примеров трассировок), чтобы ассистент мог предоставить ссылку, по которой можно перейти. В сеансе OAuth, где рабочую область не удалось определить, ссылки не добавляются, а не угадываются.

У трассировок нет URL: ссылку на трассировку нельзя получить из полей, возвращаемых read или list, а угаданный формат приведёт к ошибке 404. Вместо этого инструкции сеанса задают шаблон .../v1/session/redirect/projects/?trace_id={trace_id}&path=..., чтобы ассистент подставил идентификатор и предоставил ссылку. Она проходит через перенаправление opik-backend, которое определяет проект и рабочую область по трассировке, поэтому работает там, где прямая ссылка на проект не работает, в том числе в сеансе OAuth с неопределённой рабочей областью. Это та же ссылка, которую Python SDK выводит для трассировки.

`list`

Просматривайте коллекцию или выполняйте поиск по ней с постраничной выдачей. Для типов, относящихся к проекту (trace, span, thread, agent_insights_issue, dataset_item, prompt_version), нужен родительский объект: UUID или имя проекта, UUID набора данных либо UUID промпта.

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

Фильтры. Для trace, span, thread, experiment и dataset_item принимается строка OQL с той же грамматикой, что и search_traces(filter_string=…) в SDK:

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

Строки заключаются в двойные кавычки, числа указываются без кавычек, duration задаётся в миллисекундах, даты — это моменты времени в формате ISO-8601 с часовым поясом ("2026-09-08T10:00:00Z"). Для оценок и словарей указывается ключ: feedback_scores.accuracy < 0.5, metadata.environment = "prod". AND — единственный оператор соединения.

Как и на странице Logs в интерфейсе, в списки трассировок, спанов и потоков добавляется source = "sdk", чтобы трассировки оценщика, песочницы и эксперимента не мешали; укажите имя source самостоятельно, чтобы увидеть их. Первая строка вывода повторяет применённый фильтр.

Некорректный фильтр отклоняется до обращения к бэкенду с подсказкой, как его исправить: позиция синтаксической ошибки, наиболее близкое имя поля, допустимые операторы для типа поля или ожидаемый формат значения. Поля с ограниченным набором значений (source, span type, thread status, visibility_mode) тоже проверяются по этому набору, включая каждый элемент списка in. source — единственное поле, которое проверяет сам бэкенд: на неизвестное значение он отвечает кодом 500, а не 400, поэтому source = "SDK" иначе вызвал бы непрозрачную ошибку сервера из-за заглавной буквы. Остальные поля сравниваются как строки и возвращают пустую страницу, что читается как «совпадений нет», хотя на самом деле означает «такого значения нет». Запросите schema("list.trace") (или list.span, list.thread, list.experiment), чтобы получить полный справочник полей, включая допустимые значения.

Поиск одного элемента в наборе данных. list(entity_type="dataset_item", dataset_id=…) filters on the case itself: data.<key> — для ключей, с которыми был создан набор данных, full_data — для подстроки во всём содержимом (полное сканирование — по возможности укажите ключ), а также id, tags, source, trace_id, span_id и временные метки. data.<key> принимает только шесть строковых операторов (=, !=, contains, not_contains, starts_with, ends_with); бэкенд отвечает кодом 400 на сравнение, поэтому этот запрос отклоняется до вызова. У конечной точки нет сортировки и полнотекстового поиска — sort отклоняется, а не игнорируется. read(entity_type="dataset_item", id=…) возвращает элемент целиком — так можно получить значение, обрезанное в таблице.

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

С experiment_ids тот же список становится сравнением — элементами с прикреплёнными запусками — и фильтруется по запускам (feedback_scores.<name>, output, duration). Это разные наборы полей для двух конечных точек бэкенда: schema("list.dataset_item_case") — собственные элементы набора данных, schema("list.dataset_item") — сравнение.

Сортировка. trace, span, thread и experiment принимают sort="<field> [asc|desc]", по умолчанию desc, и только одно поле: sort="duration desc", sort="total_estimated_cost", sort="feedback_scores.accuracy asc", sort="usage.total_tokens". Перед вызовом поле проверяется по списку полей, доступных для сортировки у данного типа сущности, поскольку бэкенд молча игнорирует поля, по которым нельзя сортировать. В очень больших рабочих пространствах бэкенд полностью отключает сортировку; в этом случае об этом сообщается в заголовке.

dataset_item сортирует только сравнение (с помощью experiment_ids): конечная точка элементов не принимает параметр сортировки, поэтому сортировка обычного списка отклоняется, а не игнорируется.

Временной интервал и поиск. trace, span и thread принимают since и until: каждый из них может быть относительным интервалом ("30m", "1h", "7d") или моментом времени в формате ISO-8601 с часовым поясом, поэтому для «последнего часа» не нужно вычислять время вручную. Интервал определяется по времени создания записи — это не создаёт большой нагрузки на бэкенд и для текущего трафика совпадает с start_time с точностью до нескольких секунд. Чтобы задать точную границу, укажите start_time в filters. Те же три типа принимают search — произвольный текст, который ищется в любом месте идентификатора, имени, входных и выходных данных, метаданных, тегов и идентификатора потока. Поиск сканирует весь проект на бэкенде, поэтому первый запрос для большого проекта может занять десятки секунд. Для таких запросов установлен тайм-аут в 60 секунд. Добавьте since, чтобы снова ускорить их.

Чтение таблицы. Длительности помечены как duration_ms / ttft_ms и показаны в целых миллисекундах; поле остаётся duration в filters и sort. Временные метки отображаются с точностью до секунды, а стоимость — обычными десятичными числами. В строках проектов есть last_updated_trace_at, чтобы было видно, в каком проекте идёт текущий трафик; в строках потоков отображается первое сообщение. Пустая страница при заданном временном интервале сообщает, когда в проекте появилась последняя трассировка, а пустая страница при фильтре по умолчанию source = "sdk" подсказывает, как посмотреть другие источники. Если указать имя project_name с опечаткой, в ответе будет ближайшее существующее имя.

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

Проблемы диагностики. agent_insights_issue — это страница Diagnostics, доступная через MCP: повторяющиеся сбои, сгруппированные заданием Diagnostics в Opik для проекта и отсортированные так же, как в интерфейсе (сначала недавно обнаруженные). Столбцы: severity, status, total_occurrences (сумма за всё время), latest_count (последний день отчёта — дата, на которую ссылается описание самой проблемы) и last_seen. По умолчанию отображаются открытые проблемы; передайте status="resolved" или "closed", чтобы посмотреть остальные. read и list также доступны под именем issue, которым эти проблемы называются в интерфейсе; полное имя используется в перечислении entity_type, поэтому одна и та же сущность не отображается там дважды. Счётчики учитывают весь период, чтобы совпадать с интерфейсом; тот же интервал since / until, что и для трассировок, сужает временной диапазон до дней отчёта в UTC, поскольку Diagnostics агрегирует данные по дням.

Пустой список объясняет причину: иначе «ничего не сломалось» и «Diagnostics не включена» выглядели бы одинаково. Возможны пять состояний: Diagnostics недоступна в этом развёртывании, не включена для проекта, отключена, включена, но давно не запускалась, или включена и не обнаружила проблем с указанием времени последнего сканирования. В состояниях, где можно что-то сделать, указано, какой вызов выполнить; каждое состояние также содержит ссылку на страницу Diagnostics проекта.

Непустой список содержит даты. Проблемы — это группы, сформированные при последнем сканировании, поэтому ответ заканчивается на Report covers data through <time>; если запрошенный интервал выходит за его пределы, указывается непокрытая часть и способ её закрыть: запустить сканирование, охватывающее нужный период, или посмотреть исходные трассировки с помощью since. Если запросить неделю для проекта, который сканируется каждую ночь, в сгруппированном ответе не будет последнего дня; здесь об этом сообщается.

write("agent_insights_job.enable", {"project_name": "demo"}) включает Diagnostics. После этого сканирование выполняется ежедневно; повторный вызов безопасен. write("agent_insights_job.trigger", …) немедленно сканирует последние 24 часа, не дожидаясь ночного запуска. Для обоих вызовов требуется то же разрешение, что и для чтения проблем; оба отклоняются, если в развёртывании нет Diagnostics.

Проблема проходит жизненный цикл с помощью write("agent_insights_issue.resolve", {"issue_id": "<uuid>", "project_name": "demo"}) — пометить как устранённую — или …close, если она не требует действий, и …reopen, чтобы вернуть её в список открытых. Для всех трёх действий требуется одно и то же разрешение; в ответе приводится ссылка на представление, куда переместилась проблема, поскольку устранённая проблема больше не отображается на странице по умолчанию. Решение о том, устранён ли сбой, зависит от ситуации, поэтому выполняйте эти действия только по запросу: помощник не должен самостоятельно наводить порядок в списке во время анализа проблем.

Метрики во времени. project_metric строит таблицу временных интервалов с одной метрикой проекта: количеством трассировок, спанов и потоков, длительностью, частотой ошибок, стоимостью, использованием токенов и оценками обратной связи. Это помогает ответить на вопрос, который возникает после обзора: когда что-то изменилось?

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

Строки — это временные интервалы, а не записи, поэтому page, size и sort отклоняются, а не игнорируются. interval принимает hourly, daily, weekly или total; если не указать значение, интервал выбирается по временному диапазону, как на вкладке Metrics: почасовой — до 3 дней, дневной — до 30, недельный — для более длительных периодов. Поэтому график по умолчанию содержит несколько десятков строк независимо от диапазона, а почасовой график за месяц (721 строка) нужно запрашивать отдельно. since / until принимают те же форматы, что и везде, и по умолчанию охватывают последние 7 дней. Для filters используются поля той сущности, к которой относится метрика, поэтому метрику спанов фильтруют по полям спанов.

breakdown разбивает каждый интервал по tags, name, error_info, error_type, model, provider, span_type, guardrail_name или metadata.<key>. Не каждая метрика поддерживает все эти варианты, а семь метрик не поддерживают ни один; инструмент знает, какие варианты доступны, и сообщает об этом до вызова бэкенда, указывая метрику, которая отвечает на тот же вопрос, если такая есть. Три семейства метрик возвращают сразу несколько рядов (длительность — p50/p90/p99, оценка обратной связи — по имени, использование токенов — по ключу), а при группировке бэкенд строит график только для одного из них, поэтому series= выбирает его: процентиль, имя оценки или ключ использования. Для длительности по умолчанию используется p50, для использования токенов — total_tokens; выбранное значение указывается в первой строке.

Пустые интервалы не отображаются, а их количество указывается ниже, поэтому тихий месяц представлен несколькими строками, а не столбцом нулей; для интервала без трассировок частота не указывается, а не отображается как ноль.

Запросите schema("list.project_metric"), чтобы получить таблицу метрик, интервалы и матрицу группировки по метрикам.

Имена проекта. score_name перечисляет имена оценок обратной связи, записанные в проекте, а online_rule — оценщики правил автоматизации, настроенных для него; именно оттуда берётся большинство таких имён. Оба вызова возвращают те же списки, что и read("project", …), целиком и с постраничной выдачей, если ограниченного списка в обзоре недостаточно.

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

`write`

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

Операции:

Операция	Назначение
`trace.create`	Записать одну трассировку (или пакет). Родительская сущность для спанов / оценок / комментариев.
`trace.update`	Завершить или изменить существующую трассировку.
`span.create`	Записать спан для существующей трассировки (или пакет спанов).
`score.create`	Добавить числовую оценку обратной связи к трассировке, спану или потоку.
`comment.create`	Добавить текстовый комментарий к трассировке, спану или потоку.
`prompt_version.save`	Сохранить новую версию промпта (создать промпт с указанным именем, если его нет).
`dataset.create`	Создать набор данных — `type: "test_suite"` превращает его в тестовый набор для оценки.
`dataset_item.upsert`	Добавить или обновить элементы набора данных (всегда в формате оболочки).
`experiment.create`	Создать эксперимент, связанный с набором данных.
`experiment_item.create`	Добавить в эксперимент строки трассировки и dataset_item.
`thread.close`	Закрыть поток (пометить как неактивный). Передайте `thread_id` и проект.
`thread.open`	Повторно открыть закрытый поток. Передайте `thread_id` и проект.
`agent_insights_job.enable`	Включить Diagnostics для проекта (ежедневное сканирование, повторный вызов безопасен).
`agent_insights_job.trigger`	Немедленно запустить сканирование Diagnostics за последние 24 часа.
`agent_insights_issue.resolve`	Пометить проблему Diagnostics как устранённую (сначала спросите пользователя).
`agent_insights_issue.close`	Пометить проблему Diagnostics как не требующую действий (сначала спросите пользователя).
`agent_insights_issue.reopen`	Вернуть устранённую или закрытую проблему Diagnostics в список открытых.
`annotation_queue.create`	Создать очередь аннотаций проекта, при необходимости указав пользовательское представление аннотатора.
`annotation_queue.update`	Изменить очередь аннотаций: задать, заменить или очистить представление аннотатора.

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

Один и тот же инструмент отвечает на запросы list.trace, list.span, list.thread и list.experiment справочной информацией инструмента list об этой сущности: все поля, доступные для фильтрации, с их типами и допустимыми операторами, поля для сортировки, сведения о том, применимы ли временной интервал и полнотекстовый поиск, а также два примера фильтров.

schema(operation="list.trace")

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

Эти параметры настраивают локальный сервер; каждый из них задаётся переменной окружения. Размещённый сервер в Opik Cloud их не использует.

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

Переменная	Значение по умолчанию	Примечания
`OPIK_API_KEY`	—	Ключ API для самостоятельно размещённого Comet или для Opik Cloud без размещённого сервера. Для Opik с открытым исходным кодом он не нужен, если только в развёртывании не включена аутентификация.
`OPIK_WORKSPACE`	не задано	Имя рабочего пространства. В облаке при наличии ключа API, если параметр не задан, отправляется `default`, который указывает на рабочее пространство по умолчанию вашей учётной записи. Задайте его явно, если работаете в другом пространстве, иначе данные будут незаметно считываться не из того рабочего пространства. При OAuth оставьте параметр незаданным (токен содержит это значение); для локальной версии и версии с открытым исходным кодом (`default` — единственное рабочее пространство).
`COMET_WORKSPACE`	—	Устаревший псевдоним для `OPIK_WORKSPACE` (для обратной совместимости). Если заданы оба параметра, приоритет имеет `OPIK_WORKSPACE`.
`COMET_WORKSPACE_ID`	не задано	Необязательный UUID рабочего пространства. Если задан, добавляется в события аналитики и имеет приоритет над определённым значением. Обычно не требуется: при установке с OAuth UUID автоматически берётся из токена.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Укажите адрес своего самостоятельно размещённого узла Comet или `https://dev.comet.com` для промежуточной среды.
`OPIK_URL`	определяется на основе `COMET_URL_OVERRIDE` + `/opik/api`	Задайте для Opik с открытым исходным кодом, API которого доступен по адресу `/api` (локально — `http://localhost:5173/api`). На платформе Comet переопределяйте только в том случае, если 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. Необходим, чтобы хосты MCP могли начать процесс OAuth через HTTP.
`OPIK_MCP_RESOURCE_URI`	не задано	Канонический общедоступный URI этого сервера, объявляемый как `resource` в метаданных защищённого ресурса и используемый для определения подсказки `WWW-Authenticate`.
`OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S`	`30`	Как долго доверять ответу «действителен» от проверки токена opik-backend, прежде чем следующий запрос с тем же токеном OAuth снова выполнит проверку. Ограничивает нагрузку на серверную часть из-за проверки каждого запроса и период, в течение которого просроченный токен всё ещё передаётся дальше (этот период также заканчивается при первом ответе 401 от серверной части). Ограничивается значением `expires_at` самого токена, если серверная часть его сообщает.
`OPIK_MCP_LOG_LEVEL`	`INFO`	Пороговый уровень журналирования stderr.

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

Два формата токенов Bearer — два контракта для HTTP-транспорта. Токен доступа OAuth opik_mcp_at_… проверяется при каждом запросе через конечную точку проверки токенов opik-backend (результат кэшируется, см. OPIK_MCP_OAUTH_VALIDATION_CACHE_TTL_S). Для просроченного или отозванного токена возвращается HTTP 401 с WWW-Authenticate: Bearer error="invalid_token"; на это хосты MCP ориентируются при выполнении фонового предоставления разрешения refresh_token. Ключ API Opik не проверяется локально: он без изменений передаётся в opik-backend, который является единственной точкой проверки. Выбирайте транспорт с учётом конфигурации развёртывания:

Сценарий	Транспорт
Opik Cloud	Ничего запускать не нужно: размещённый сервер — это этот сервер по HTTP, запущенный Comet
Клиент MCP и Opik на одном компьютере (локальная установка OSS)	stdio (рекомендуется — проще всего, без порта и настройки OAuth)
Локальный клиент MCP → самостоятельно размещённый Opik	stdio с переменными окружения для развёртывания или HTTP с OAuth (`OPIK_MCP_AS_URL` указывает на серверную часть)
opik-mcp размещён за тем же пограничным узлом, что и opik-backend	HTTP — серверная часть проверяет токены Bearer при каждом запросе

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

Телеметрия

Переменная	Значение по умолчанию	Примечания
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Задайте `false`, чтобы отключить всю телеметрию, кроме Sentry.
`OPIK_MCP_SENTRY_ENABLED	`true`	Set to `false` — отключить всю телеметрию Sentry.
=======

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

Хосты различаются по времени, которое они позволяют выполнять одному вызову инструмента:

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

Если вызов зависает, задайте OPIK_MCP_LOG_LEVEL=DEBUG, чтобы включить полный журнал запросов.

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

Настройка работает? Запустите сервер с переменными окружения из конфигурации клиента и --check: OPIK_URL=http://localhost:5173/api uvx opik-mcp@latest --check. Он выведет имя рабочего пространства и видимые ему проекты либо сообщит, что нужно исправить. В сообщениях об ошибках самого сервера также указано, что изменить, и приведена ссылка на соответствующую страницу документации.

Не подхватывается OPIK_API_KEY — переменная не передаётся процессу сервера. В Claude Code / Cursor / VS Code переменные окружения применяются только внутри блока env конфигурации сервера MCP, а не в оболочке; Codex также передаёт только имена, перечисленные в env_vars. После изменения конфигурации начните новый сеанс: клиенты считывают её при запуске сеанса.

Запросы направляются на /opik/api в Opik с открытым исходным кодом — COMET_URL_OVERRIDE предназначен для самостоятельно размещённой платформы Comet. В версии с открытым исходным кодом API доступен по адресу /api: вместо этого задайте OPIK_URL=http://localhost:5173/api (или https://<host>/api). При запуске сервер предупреждает об этом, если хост — этот компьютер, а --check отвечает: «Нет API Opik по адресу …».

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

Сервер не отображается, вход не открывается, выбрано не то рабочее пространство, uvx не найден. Эти случаи описаны в разделе устранения неполадок документации. uvx opik@latest mcp status перечисляет все клиенты, в которых настроен сервер, и показывает, расходится ли их конфигурация с текущей.

Разработка

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

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

Цель	Назначение
`make install`	`uv sync --locked --extra dev`
`make run`	Запустить сервер MCP (по умолчанию — stdio).
`make run-dev`	Запустить с журналированием DEBUG и `--reload` uvicorn.
`make dev`	Запустить через `mcp dev` (обёртку Inspector для режима разработки).
`make inspect`	Запустить MCP Inspector для работающего сервера.
`make test`	`uv run pytest -q`.
`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, 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

Помощь

Создайте issue, если обнаружили ошибку или хотите предложить новую функцию
Документация Opik — документация по SDK и серверной части
Сообщество Comet в Slack — задавайте вопросы

Лицензия

Apache-2.0.

Comet Opik

Что можно делать с Comet Opik MCP?

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

MCP-сервер Opik

Быстрый старт

Opik Cloud: размещённый сервер

Плагин Claude Code

Opik с самостоятельным размещением и Opik с открытым исходным кодом: локальный сервер

Установка с помощью агента для написания кода

Настройка вручную (без проверки Opik и набора навыков)

Размещённый сервер (Opik Cloud)

Claude Code, вручную

Codex, вручную

Cursor, вручную

VS Code Copilot, вручную

Другие клиенты

Opik Cloud с ключом API

Локальный сервер (Opik с самостоятельным размещением и с открытым исходным кодом)

Claude Code, вручную

Codex, вручную

Cursor, вручную

VS Code Copilot, вручную

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

Переходите с npx opik-mcp?

Инструменты

read

list

write

schema

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

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

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

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

Телеметрия

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

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

Разработка

Помощь

Лицензия

Переходите с `npx opik-mcp`?

`read`

`list`

`write`

`schema`