Compeller MCP Server

официальный

Создавайте AI-музыкальные видео и аудиореактивные визуализации из песен через MCP.

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

Конечная точка Compeller MCP (`/api/mcp`)

Конечная точка Compeller MCP реализует Model Context Protocol как тонкую обёртку JSON-RPC 2.0 поверх существующего REST API v1. Она предназначена для интеграторов агентов (Claude Desktop, Cursor, пользовательские MCP-клиенты, DigiRAMP), которые работают с MCP нативно, а не через чистый HTTP.

Транспорт: Потоковый HTTP (одно сообщение JSON-RPC на один HTTP POST).
URL: POST https://compeller.ai/api/mcp
Версия протокола: 2024-11-05
Имя / версия сервера: compeller-mcp / см. результат initialize.
Контракт инструментов: Приведённый ниже список инструментов является публичным контрактом интеграции. Используйте tools/list для получения актуального набора, объявленного на развёрнутом сервере.
Списки каталогов: Официальный реестр MCP · Smithery · Glama

Аутентификация

Анонимные (ознакомительные) методы: initialize, tools/list, ping, notifications/initialized, а также анонимные инструменты get_capabilities, get_pricing, list_styles.

Все остальные инструменты требуют передачи токена Compeller API в самом HTTP-запросе, а не в теле JSON-RPC. Подойдёт любой из заголовков:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

Токены выпускаются для каждого User Compeller (те же токены, что используются /api/v1/*). Агенты могут получить его одним из двух способов:

Попросить пользователя войти в систему, открыть Аккаунт → Доступ к API, показать токен и вставить его в защищённое хранилище агента.
Использовать существующую конечную точку входа и отправить access_token в качестве токена-носителя. Заголовок Cookie не требуется и не ожидается:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"[email protected]","password":"..."}'

Обычные пользователи получают username и access_token. roles появляется только для аккаунтов с ролями, выходящими за рамки базовой ROLE_COMPELLER; refresh_token и expires_in появляются только если они не пусты.

Или обменять учётные данные через вспомогательный модуль аутентификации v1, который возвращает постоянный токен API:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"..."}'

Отсутствующий или недействительный токен отображается как ошибка инструмента (isError: true) с сообщением "API token required." / "Invalid API token.", а не как ошибка JSON-RPC, чтобы MCP-клиенты могли запросить у пользователя учётные данные.

Методы JSON-RPC

Метод	Назначение	HTTP-результат
`initialize`	Рукопожатие возможностей. Возвращает `protocolVersion`, `serverInfo`, `capabilities`.	200 JSON-RPC результат
`notifications/initialized`	Подтверждение клиента. Без тела ответа.	204
`tools/list`	Список всех инструментов со схемой и описанием.	200 JSON-RPC результат
`tools/call`	Вызов инструмента. `params = {name, arguments}`.	200 JSON-RPC результат (ошибки инструмента возвращаются как `{isError: true, content: [...]}`)
`ping`	Поддержание соединения (no-op).	200 JSON-RPC `result: {}`

Неизвестные методы возвращают ошибку JSON-RPC -32601 Method not found. Неизвестные имена инструментов возвращают -32602 Unknown tool. Некорректное тело JSON возвращает -32700 Parse error. Отсутствующий / неверный jsonrpc или отсутствующий method возвращает -32600 Invalid Request.

Инструменты

Все инструменты возвращают одну запись content типа type: text, поле text которой содержит структурированный вывод в формате JSON. При сбое возвращается та же форма ответа с isError: true и читаемым сообщением об ошибке в content[0].text — никогда как JSON-RPC error.

Обнаружение (без аутентификации)

Инструмент	Входные данные	Возвращает
`get_capabilities`	—	`productName`, `version`, `capabilities[]`, `spec_url`, `enums` (`styles`, `target_platforms`, `aspect_ratios`), `auth`, `media_limits`, `rate_limits`
`get_pricing`	—	`plans[]` с `id`, `name`, `monthlyUsd`, `features[]`
`list_styles`	—	`styles[]` с `id`, `name` (значение `id` — это точное значение, которое `create_compel` / `create_compel_from_music` принимают для `style`)

Медиа и музыка (требуется аутентификация, если не указано иное)

Инструмент	Обязательные	Необязательные	Возвращает
`search_music`	`query`	`limit`	Результаты публичного поиска музыки, подходящие для `create_compel_from_music`. Аутентификация не требуется.
`upload_media`	—	`name`, `mime_type`, `type`	Инструкции по загрузке, указывающие на `POST /api/v1/media`
`search_media`	—	`type` (`audio`/`image`/`video`/`text`), `limit` (≤100, по умолчанию 20), `offset`	`media[]`, `paging`

Compels (требуется аутентификация)

Инструмент	Обязательные	Необязательные	Возвращает
`create_compel_from_music`	`track_id`	`title`, `style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status`, `next_action`
`create_compel`	`title`, `primary_media_id`	`style`, `target_platform`, `aspect_ratio`, `artist_context`	`compel_id`, `status: QUEUED`
`get_compel`	`compel_id`	—	`compel_id`, `title`, `status`, `progress_percent`, `stage`, `rendering_id`, `created_at`, `human_url`, `next_action`
`start_render`	`compel_id`	—	Запускает финальный рендеринг, когда compel готов; возвращает статус и следующее действие.
`cancel_compel`	`compel_id`	—	Отменяет выполняющийся compel (идемпотентно — уже ОТМЕНЁННЫЙ завершается успешно); возвращает `compel_id`, `status: CANCELLED`, `stage`.
`list_compels`	—	`limit` (≤100), `offset`	`compels[]`, `paging`
`search_compels`	`query`	`limit`	`compels[]`, `count`

style, target_platform и aspect_ratio ограничены enum в схемах инструментов (см. get_capabilities.enums); значения style берутся напрямую из list_styles.

Аккаунт (требуется аутентификация)

Инструмент	Входные данные	Возвращает
`get_account_credits`	—	`plan`, `minutes_remaining`, `free_minutes_remaining`, `paid_minutes_remaining`, `minutes_total`, `quota_exceeded`, `api_eligible`, `billing_url` — вызывайте перед дорогостоящим рендерингом для принятия решений с учётом стоимости.

Рендеринги (требуется аутентификация)

Инструмент	Обязательные	Возвращает
`list_renderings`	`compel_id`	`compel_id`, `renderings[]` с `rendering_id`, `status`, `download_url`
`get_rendering`	`rendering_id`	`rendering_id`, `compel_id`, `status`, `download_url`

download_url указывает на GET /api/v1/renderings/{id}/download (поддерживает HTTP Range). Ответы завершённого compel/rendering также включают передачу react с бесплатной загрузкой REACT (https://compeller.ai/download/desktop) и URL для получения дополнительной информации (https://compeller.ai/react), чтобы агенты могли сообщить пользователям, как испытать compel в качестве живой системы исполнения.

Вебхуки (требуется аутентификация)

Агенты, интегрирующиеся с Compeller, могут самостоятельно регистрироваться для получения подписанных push-уведомлений о событиях жизненного цикла compel вместо опроса get_compel. Подпишитесь на compel.ready, чтобы узнать момент, когда compel можно рендерить (затем вызовите start_render) без опроса; compel.completed / compel.failed являются конечными событиями.

Инструмент	Обязательные	Необязательные	Возвращает
`register_webhook`	`url` (HTTPS, ≤2048 символов)	`events[]` — по умолчанию `[""]`; известные значения: ``, `compel.ready`, `compel.completed`, `compel.failed`	`webhook_id`, `url`, `events`, `secret` (возвращается ровно один раз), `active`, `created_at`
`list_webhooks`	—	—	`webhooks[]` — `webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`. Секреты никогда не возвращаются этим инструментом.
`update_webhook`	`webhook_id`	`url`, `events[]`, `active` — хотя бы одно	`webhook_id`, `url`, `events`, `active`, `created_at`, `updated_at`. Секреты никогда не возвращаются; используйте для этого `rotate_webhook_secret`.
`delete_webhook`	`webhook_id`	—	`webhook_id`, `deleted: true`
`test_webhook_delivery`	`webhook_id`	—	`webhook_id`, `event_id`, `event_type: "webhook.test"`, `delivered`, `response_status?`, `response_body_preview?`, `latency_ms`, `error?`. Синхронный — инструмент ожидает ответа от конечной точки интегратора (макс. 5 с). Секреты никогда не возвращаются.
`rotate_webhook_secret`	`webhook_id`	—	`webhook_id`, `url`, `events`, `active`, `secret` (новый — возвращается ровно один раз), `created_at`, `updated_at`. Старый секрет немедленно аннулируется.

Неизвестные имена событий автоматически сводятся к универсальному *; это отражает POST /api/v1/webhooks, так что агент никогда не создаст бездействующую подписку.

Доставка — как минимум один раз. Каждое событие отправляется немедленно, и, если ваша конечная точка недоступна или возвращает не-2xx, повторяется с отсрочкой — до 6 попыток всего (немедленно, затем через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч). Каждая попытка несёт один и тот же X-Compeller-Event-Id и побайтово идентичное подписанное тело, поэтому выполняйте дедупликацию по этому идентификатору. Если все попытки исчерпаны, событие отбрасывается; сверяйтесь через get_compel.

register_webhook отклоняет адреса назначения, указывающие на внутреннюю инфраструктуру, с ошибкой инструмента: loopback, частные диапазоны RFC1918, link-local (включая IP метаданных облака, такие как 169.254.169.254), IPv6 ULA, CGNAT, multicast, неопределённый адрес и имена хостов, заканчивающиеся на .local / .internal / .localhost. Та же проверка повторно выполняется во время доставки для разрешённого DNS при каждой попытке, поэтому имя хоста, которое после регистрации привязывается к заблокированному IP, пропускается для этой попытки (с записью в журнал); если оно остаётся заблокированным, оно просто расходует свой бюджет повторных попыток и затем отбрасывается.

test_webhook_delivery отправляет синтетическое событие webhook.test с подписью HMAC-SHA256 и синхронно ожидает ответа от конечной точки. Он игнорирует подписанный events конечной точки (всегда доставляется) и применяет ту же проверку безопасности URL, что и реальные доставки. Ответ не-2xx отображается как delivered: false, но сам вызов MCP всё равно завершается успешно — результатом является полезная нагрузка.

update_webhook принимает любое из url, events, active (хотя бы одно). Проверка URL аналогична register_webhook. Секреты никогда не возвращаются этим инструментом.

rotate_webhook_secret создаёт новый 64-символьный шестнадцатеричный секрет подписи, возвращает его ровно один раз и немедленно аннулирует предыдущий секрет. Сохраните новый секрет при получении до следующей реальной доставки.

Каждая доставка подписывается точно так же, как и в REST-пути — см. раздел Webhooks в openapi.yaml для полного контракта конверта и заголовков.

Пример сеанса

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

Ответом на шаг 3 является JSON-RPC result, содержащий content[0].text — сам по себе JSON-документ с webhook_id, secret и т.д. Немедленно сохраните secret; сервер не вернёт его снова.

Коды ошибок

Код	Значение	Причина
`-32700`	Ошибка разбора	Тело не является допустимым JSON
`-32600`	Неверный запрос	Отсутствует/неверный `jsonrpc`, отсутствует `method`, пустое тело
`-32601`	Метод не найден	Неизвестный метод JSON-RPC
`-32602`	Неверные параметры	Неизвестный инструмент, отсутствует `name` инструмента, неверная форма `params`
`-32603`	Внутренняя ошибка	Необработанное исключение (записывается в журнал на стороне сервера)

Сбои на уровне инструмента (валидация, аутентификация, не найдено) возвращаются внутри успешного ответа JSON-RPC как {result: {isError: true, content: [{type: "text", text: "..."}]}}. Это соответствует соглашению MCP — позволяет LLM видеть и отображать сбой дословно. Дерево решений для аудио агента: если пользователь предоставляет MP3/WAV/FLAC, используйте upload_media, затем create_compel; если пользователь предоставляет только строку с названием песни/исполнителем, используйте search_music, затем create_compel_from_music; не синтезируйте тон, если явно не запрошен сгенерированный тестовый звук.