Artillect MCP

Подключите генерацию изображений и видео в Codex, ChatGPT, Claude, Cursor, Hermes и любой MCP-клиент. Один URL, OAuth или API-ключ, тот же баланс что в Studio.

Быстрое подключение

Это MCP-сервер, а не веб-страница. Скопируйте URL и добавьте его в своём клиенте — подключение и OAuth всегда делает человек (агент не может вписать коннектор сам).

URL

https://app.artillect.pro/mcp
  • Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → вставьте URL → Authenticate.
  • Claude Code (CLI): claude mcp add --transport http artillect https://app.artillect.pro/mcp → /mcp → Authenticate.
  • Codex / Cursor / Hermes: см. свой раздел ниже (Streamable HTTP + OAuth).

После подключения наберите /mcp__artillect__quickstart (Claude) или попросите агента вызвать get_started — дальше он сам пойдёт по циклу generate → get_task.

Remote URL

Production

https://app.artillect.pro/mcp

Staging

https://dev.artillect.pro/mcp

Codex Desktop

Это MCP endpoint, а не обычная веб-страница. Transport — Streamable HTTP.

  1. Settings → MCP servers → Add server
  2. URL: https://app.artillect.pro/mcp, затем сохраните сервер
  3. Нажмите Authenticate и завершите OAuth в браузере
  4. После подключения перезапустите Codex или откройте новую задачу
  5. Проверьте сервер через /mcp, затем дайте агенту первый запрос ниже
  6. Для результата генерации Codex должен скачать каждый файл в writable workspace, проверить его и встроить в финальный ответ абсолютным локальным путём. Защищённый remote URL или image block внутри tool output сами по себе доставкой не считаются.

Первый запрос агенту

Вызови Artillect get_started, затем get_balance. Для генерации используй generate_image, возьми task_id/poll_args из ответа и вызывай get_task до done: true и непустого media_urls. После этого доставка ещё не завершена: скачай каждый media_url в writable workspace, проверь файл и покажи его в финальном ответе абсолютным локальным путём. Remote URL — только запасная ссылка. Не показывай результат только если я явно это попросил.

ChatGPT Web / Work

После публикации в ChatGPT MCP подключается через установленный плагин Artillect и его OAuth. Добавление URL в локальные настройки Codex Desktop не подключает этот сервер к ChatGPT Web. В рабочем workspace доступность и установка плагина могут контролироваться администратором.

  1. Если плагин уже опубликован или установлен в workspace, выберите Artillect
  2. Завершите OAuth-связывание аккаунта
  3. В новом чате попросите вызвать get_started

Claude (Connectors)

  1. Settings → Connectors → Add custom connector
  2. Name: Artillect, URL: production или staging выше
  3. Authenticate (OAuth, scope mcp) или Bearer art_…
  4. Спросите: «сгенерируй картинку…» / «видео…» — агент вызовет tools и поллит get_task

Или наберите слэш-команду /mcp__artillect__quickstart — холодный агент сразу вызовет get_started и пойдёт по каноническому циклу. Есть также /mcp__artillect__generate_image и /mcp__artillect__character_video.

Claude Code (CLI)

Один терминальный вызов добавляет remote MCP через HTTP transport:

Add server

claude mcp add --transport http artillect https://app.artillect.pro/mcp
  1. Выполните команду выше (staging — тот же вызов с https://dev.artillect.pro/mcp)
  2. В сессии наберите /mcp → выберите artillect → Authenticate (OAuth в браузере, scope mcp)
  3. Стартуйте с слэш-команды /mcp__artillect__quickstart (или дайте первый запрос ниже)

Первый запрос агенту

Вызови Artillect get_started, затем get_balance. Для генерации используй generate_image, возьми task_id/poll_args из ответа и вызывай get_task до done: true и непустого media_urls. После этого доставка ещё не завершена: скачай каждый media_url в writable workspace, проверь файл и покажи его в финальном ответе абсолютным локальным путём. Remote URL — только запасная ссылка. Не показывай результат только если я явно это попросил.

Cursor

Remote MCP (рекомендуется). Вставьте в MCP settings / mcp.json:

mcp.json snippet

{ "mcpServers": { "artillect": { "url": "https://app.artillect.pro/mcp" } } }

Хост откроет OAuth (IdP поддерживает Dynamic Client Registration + PKCE). Альтернатива: stdio + ARTILLECT_API_KEY. Агент: сначала get_started (рецепты + дефолты). Resource artillect://agent/recipes. Remote upload: upload_file с публичным HTTPS url (/api/v1/files/from-url), create_upload_url + PUT (image/audio), или file_base64 + filename (у hosted нет клиентского диска; file_path — только stdio). get_task — wait_sec (рекомендуем 60 + повтор, max 300). Это единственный polling-инструмент для всех модальностей — kind выводится из task_id. Канонический идентификатор — task_id; id и taskId оставлены как aliases. list_models по умолчанию slim; каждая модель несёт parameters — машиночитаемые допустимые значения (aspect_ratio / resolution / quality / output_format / …), не надо угадывать (detail: full добавляет aliases и остальное). Медиа — тот же MinIO/S3, что Studio; дверь агента — /api/v1/files/* (API key / OAuth), не Studio session multipart.

Hermes Agent

OAuth без API-ключа (рекомендуется). Первичный логин — в интерактивном терминале у человека: агент в неинтерактивном шелле не может открыть браузер. После логина перезапустите приложение Hermes — tools подхватываются на старте (mcp_artillect_*).

Production (OAuth)

hermes mcp add artillect --url https://app.artillect.pro/mcp --auth oauth hermes mcp login artillect

Staging (OAuth)

hermes mcp add artillect-staging --url https://dev.artillect.pro/mcp --auth oauth hermes mcp login artillect-staging
  1. В своём терминале: команды выше → браузер IdP → согласие (scope mcp)
  2. Проверка: hermes mcp list / hermes mcp test artillect
  3. Рестарт Hermes (или reload MCP, если есть в UI)
  4. В новой сессии: сначала get_started, затем generate_* → get_task

Токен протух: снова hermes mcp login artillect. Альтернатива — hermes mcp add … --auth header с ключом art_… с /api. Не вставляйте ключ в чат агенту без необходимости.

Батчи: не слать много generate_* параллельно — лимит ~3 с между submit на ключ (429 + retry_after_sec). media_urls — только наш MinIO (app.artillect.pro/…/media/download), не CDN провайдера.

Что умеет агент

  • Генерация: generate_image / generate_video / upscale / SwitchX → get_task
  • Проекты и Element Library: list_projects, list_project_elements, create_image_element / create_project_element (персонажи/референсы с @name в промпте; video model kling-3 / kling-o3, не turbo)
  • Каталог и баланс: list_models, recommend_model, get_balance, estimate
  • Webhooks: upsert_webhook / list_webhook_deliveries (публичный HTTPS callback)

Доставка результата в чат (по умолчанию)

done: true означает завершение генерации, но не доставки. В Codex Desktop и других coding-host с shell агент обязан скачать каждый файл в writable workspace, проверить его и встроить в финальный ответ абсолютным локальным путём. Все URL из media_urls, не только первый. Не слать в чат — только если пользователь явно попросил не показывать результат.

Completed images по умолчанию также приходят как typed MCP image content (до 4 файлов по 5 MiB), а каждый результат — как typed resource link. Для host без клиентского shell это основной канал вместе с MCP Apps preview. Если видимое вложение невозможно, все media_urls можно дать как явно помеченный деградированный fallback, не утверждая, что inline-доставка подтверждена. Видео из-за размера остаётся resource link / URL.

Directory listing (Claude / Cursor)

Для Claude / Cursor hosted MCP готов к подаче в каталоги: OAuth + PRM, tool title и annotations (readOnlyHint / destructiveHint). Саму заявку в Anthropic / Cursor отправляет человек — агент не может «влистить» сервер автоматически.

Для публикации плагина в ChatGPT остаётся auth-runtime follow-up: объявить OAuth securitySchemes у каждого tool и возвращать mcp/www_authenticate с error и error_description из tool-level challenge. Текущий Bearer gate корректно даёт server-level 401, но останавливает запрос до tool handler.

  • MCP URL: https://app.artillect.pro/mcp · staging https://dev.artillect.pro/mcp
  • Privacy (для ревьюеров): https://app.artillect.pro/privacy
  • Test account: staging invite allowlist / ключ art_ через /api. Секреты в заявку не класть. Владелец review-аккаунта — Rustam.
  • Docs для скринов: эта страница · /docs/use-cases · /docs/features

Ops checklist (человек)

  1. Live QA: Claude custom connector + Cursor URL на staging, затем prod
  2. Claude Connectors Directory: admin-settings/directory/submissions/new (нужен Owner на Team/Enterprise org). Поля: MCP URL https://app.artillect.pro/mcp, OAuth, privacy, docs /docs/mcp, test credentials (не в git)
  3. Cursor plugins / MCP listing — если актуально
  4. Записать дату + ticket IDs в plans/156-mcp-directory-s57.md и APP_HEALTH S57

Биллинг

generate_* и chat_completion списывают токены с того же баланса, что Studio. Сначала get_balance / estimate. Ключи: /api.

Без project_id используется личный проект и ваш баланс. Для своего проекта результат тот же. В общем проекте участник обязан передать billing_source: self списывает его собственный баланс, а owner — баланс владельца проекта с проверкой роли и лимита. Неверное или пропущенное значение в общем проекте возвращает ошибку до генерации.

Use cases (UGC / overnight): /docs/use-cases · brief #for-agents · механика /docs/features

Interactive API: /docs · Human guide

Ops (вручную): QA Claude custom connector → Cursor URL → Hermes mcp login → опционально Claude directory / Cursor plugins listing.