Для чего этот сервер?

Этот MCP-сервер нужен LLM-инженерам, которые работают с Opik и хотят управлять им прямо из AI-ассистента — Claude Code, Cursor или Copilot. Вместо того чтобы переключаться между интерфейсами, разработчик читает трейсы, ставит оценки, сохраняет версии промптов и задаёт вопросы аналитику Ollie, не выходя из чата. Это ускоряет отладку и итерации LLM-приложений.

Что он умеет?

Сервер читает проекты, трейсы, спаны, тестовые наборы, эксперименты и версии промптов по ID, имени или opik:// URI, ищет их с фильтром и пагинацией, создаёт, обновляет и аннотирует их через write — логирует трейсы и спаны, проставляет оценки и комментарии, сохраняет версии промптов, управляет тестовыми наборами и экспериментами. Запускает эксперименты на тестовых наборах и задаёт вопросы аналитическому ассистенту Ollie для расследования ошибок и синтеза данных, а также показывает JSON-схемы для операций записи.

Comet-ML/Opik-MCP — MCP-сервер (официальный)

ask_ollie

Спросите Ollie, встроенного AI-ассистента Opik, что-нибудь. Используйте его для исследовательских вопросов («почему X не сработало?»), синтеза данных из разных сущностей или когда нужна предметная экспертиза. Для простых запросов вроде «покажи X» / «что такое Y» лучше использовать `read` / `list` — они дешевле. У Ollie есть прямой доступ на чтение к рабочему пространству; окружающий чат — нет. Возвращает итоговый текст ассистента и `thread_id`. По умолчанию повторно используйте этот `thread_id` в последующих вызовах — у Ollie нет памяти между тредами, поэтому если его удалить, весь предыдущий контекст потеряется. Запускайте новый тред (пропустите `thread_id`) только когда пользователь явно меняет тему. Действия, которые Ollie выполняет по ходу работы (оценки, комментарии, элементы тестовых наборов, промпты), выполняются без шага подтверждения каждого действия; авто-утверждения записываются в лог `opik_mcp.audit`.

Параметры

querystringобязательный
The user's natural-language question for Ollie, the Opik in-product assistant. Ollie can read the caller's Opik workspace (traces, experiments, projects, prompts, datasets), summarize activity, and help debug LLM apps. Be specific — Ollie sees the workspace but not the surrounding chat. Example: 'Which traces from project demo failed today and why?'
page_contextany
Free-form markdown describing what the user is currently looking at in Opik (URL, selected trace, visible filters, etc.). This is a human-readable view snapshot — NOT the place to put structured project scope (use `project_name` for that). Ollie uses this for grounding when prose alone is ambiguous. Max ~30k chars.
attach_resourcesany
List of opik:// URIs (traces, spans, experiments, prompts, …) to materialize and hand to Ollie alongside the query. The MCP server pre-resolves each URI with the same parser the `read` tool uses. Currently a no-op pending the `ollie-assist` pod ChatRequest schema accepting the field — passing it is safe; it'll be wired through once the pod side lands.
thread_idany
Thread id from a previous ask_ollie response. DEFAULT: reuse the most recent thread_id so Ollie keeps context across follow-ups. Omit ONLY on the first call, or when the user pivots to an unrelated topic (e.g. switches projects, asks about something new). When in doubt, reuse. IMPORTANT: Ollie does NOT persist project state across messages — if you set `project_name` on the first call, you must pass it again on every follow-up, even when continuing the same thread_id.
project_nameany
Opik project name to scope Ollie's reads to. Without this, Ollie's read tools query the whole workspace. Pass on every call once you know which project the user is working in — Ollie does not persist project state across messages within a thread.

list

Выводит список сущностей Opik с необязательным фильтром по имени и пагинацией. Результат — таблица с разделителем "|", содержащая id, name и несколько колонок, специфичных для сущности, а также нижний колонтитул пагинации, если есть ещё страницы. Используйте read(), чтобы получить полную информацию по любому конкретному элементу. Типы, привязанные к проекту, требуют id родителя: - trace: project_id - test_suite_item: test_suite_id - prompt_version: prompt_id Типы уровня рабочего пространства (project, experiment, prompt, test_suite) принимают необязательный фильтр по подстроке `name`.

Параметры

entity_typeenumобязательный
One of: experiment, project, prompt, prompt_version, test_suite, test_suite_item, trace.
experimentprojectpromptprompt_versiontest_suitetest_suite_itemtrace
nameany
Optional substring filter on entity name. Supported for project, experiment, prompt, test_suite; ignored for sub-collections.
pageinteger
Page number (1-indexed).
sizeinteger
Items per page. Capped at 100.
project_idany
Required when listing traces. UUID of the parent project.
test_suite_idany
Required when listing test_suite_items. UUID of the suite.
prompt_idany
Required when listing prompt_versions. UUID of the prompt.

read

Читает любую сущность Opik по ID, имени или URI вида opik:// с адаптивным сжатием. Для `id` лучше использовать UUID — это быстрее (один API-вызов) и однозначно. Поиск по имени доступен для: project, experiment, prompt, test_suite — поиск по имени медленнее (два API-вызова) и может вернуть несколько совпадений, в этом случае инструмент выводит список кандидатов, чтобы вы могли повторить запрос с правильным ID. Особые форматы: - trace: возвращает {trace, spans, spansTruncated} с до 200 spans внутри. - prompt: возвращает {prompt, versions, versionsTruncated} с до 100 версий. - Все остальные: плоская запись из /v1/private/{entity}/{id}. На выходе — однострочный заголовок `[read: …]` (entity_type, id, уровень сжатия, вернувшееся количество токенов, полное количество токенов), затем компактный JSON.

Параметры

entity_typeenumобязательный
One of: experiment, project, prompt, span, test_suite, trace.
experimentprojectpromptspantest_suitetrace
idstringобязательный
UUID, entity name (for nameable types), or full opik:// URI (e.g. opik://traces/<uuid>). When a URI is passed, entity_type is overridden from the URI.
max_tokensany
Optional token budget. If the entity is under the budget, it's returned in full; otherwise compressed to MEDIUM (long strings truncated with path hints) or SKELETON (structure only). Default ~8k tokens.

run_experiment

Отправьте эксперимент на наборе данных на основе тестового набора. opik-backend асинхронно прогоняет каждый вариант промпта по каждому элементу набора и применяет проверки оценки (scoring assertions) набора. Возвращает созданные `experiment_ids` сразу — сам запуск обычно занимает 10-30+ минут на стороне сервера. Этот инструмент работает по принципу «запустил и забыл»: он НЕ ждёт завершения. Чтобы проверить прогресс, вызывающий использует `read("experiment", <id>)`; запись эксперимента содержит `status` и `trace_count`. Результат также включает `summary_url` с глубокой ссылкой на представление сравнения в Opik UI. Используется для: повторного запуска оценки, проверки промпта на известном тестовом наборе, сравнения моделей на одном и том же тестовом наборе. НЕ поддерживает ad-hoc-наборы данных (не основанные на тестовых наборах) — для них требуется выполнение LLM на стороне клиента, чего этот инструмент намеренно не делает.

Параметры

experiment_configobjectобязательный
Experiment-execution config. Required: `dataset_name`, `dataset_id` (UUID of a test-suite dataset), `prompts` (non-empty list of `{model, messages, configs?, prompt_version_id?}`). Optional: `dataset_version_id`, `version_hash`, `project_name`. One experiment is created per prompt variant. Call `schema("run_experiment")` if the shape is unclear.

schema

Верните JSON Schema, область OAuth и один проверенный пример для полезной нагрузки `data` операции записи. Чистый поиск - без вызова бэкенда.

Параметры

operationenumобязательный
Operation whose schema to return.
trace.createtrace.updatespan.createscore.createcomment.createprompt_version.savetest_suite.createtest_suite_item.upsertexperiment.createexperiment_item.create

write

Создавайте, обновляйте или аннотируйте сущности Opik. Поле `operation` выбирает, какую пару сущность/действие вызвать; `data` содержит данные для этой операции (один объект или массив до 1000 для пакетной обработки). Операции: - trace.create: Записать один trace (или пакет). Устанавливает родителя для spans/scores/comments. (пакетная обработка разрешена) - trace.update: Завершить или изменить существующий trace по id. (пакет разрешена) - span.create: Записать один span на существующем trace (или пакет).; обязательно: trace_id (пакет разрешена) - score.create: Прикрепить числовую оценку отзыва к trace, span или thread.; обязательно: target, target_id (пакет разрешена) - comment.create: Прикрепить текстовый комментарий к trace, span или thread.; обязательно: target, target_id - prompt_version.save: Сохранить новую версию промпта. Создаёт промпт по имени, если отсутствует; BE автоматически назначает коммит, если опущен. - test_suite.create: Создать тестовый набор Opik 2.0 (набор для оценки). Путь BE остаётся /v1/private/datasets для обратной совместимости; диспетчер вставляет type='evaluation_suite' в запрос. - test_suite_item.upsert: Выполнить upsert элементов в тестовый набор. Всегда передавайте обёртку {test_suite_name|test_suite_id, items: [...]}.; обязательно: test_suite_name, test_suite_id - experiment.create: Создать эксперимент в рамках тестового набора.; обязательно: test_suite_name, test_suite_id - experiment_item.create: Прикрепить строки trace + dataset_item к эксперименту. Всегда массив-обёртка.; обязательно: experiment_id, test_suite_item_id, trace_id (пакет разрешена) Примечания: - Форма `data`: объект для одиночного, массив для пакета (где поддерживается). Операции с обязательной обёрткой (test_suite_item.upsert, experiment_item.create) принимают свой список внутри обёртки, а не на верхнем уровне. - `dry_run=true`: проверка и авторизация без вызова бэкенда. Возвращает {dry_run, would_call: {method, path, body_size}}. - При несоответствии схемы инструмент возвращает ошибку `validation_failed` с точной JSON Schema для `data` и одним исправленным примером. Вызывайте `schema(operation)` заранее…

Параметры

operationenumобязательный
The entity/verb pair to invoke. See tool description for the list. Call schema(operation) for the JSON Schema, example, and required scope.
trace.createtrace.updatespan.createscore.createcomment.createprompt_version.savetest_suite.createtest_suite_item.upsertexperiment.createexperiment_item.create
dataanyобязательный
Payload for the operation. Object for a single write, or array (max 1000 elements) for batch. Always-envelope operations (test_suite_item.upsert, experiment_item.create) take their list inside the envelope, not at the top level.
idempotency_keyany
Optional client-supplied UUID. Re-running with the same key is a no-op on the backend. Takes precedence over data.id when both are set.
dry_runboolean
Validate against the operation's schema and OAuth scope without calling the backend. Returns {dry_run: true, would_call: ...}.