Az építő egy MCP (Model Context Protocol) szervert tesz elérhetővé, így egy AI-ügynök – legyen az a Claude, a Cursor, a ChatGPT/Codex vagy a saját kliensed – irányíthatja: elindíthatsz egy buildet egy referenciakép alapján, iterálhatsz a popupon, és az eredményt kampánnyá alakíthatod. Ez a cikk bemutatja, hol hozhatsz létre hitelesítő adatot, milyen protokollt használ a végpont, és hol vannak a korlátai.

API-kulcs létrehozása

Lépj a Beállítások → API-kulcsok menüpontba. A panel a következőkkel nyílik meg:

Csatlakoztasd az OptiMonk MCP szervert AI-ügynökökhöz, mint például a Claude vagy a Cursor.

Mellette egy Dokumentáció link, amely az alkalmazáson belüli /docs/authentication cikkre mutat.

  1. Írj nevet a Kulcs neve mezőbe (a helyőrző: „e.g. Claude connection”, azaz pl. Claude kapcsolat). A név megadása kötelező; ha üresen hagyod, az „Adj nevet a kulcsnak.” üzenetet kapod.
  2. Kattints az Új kulcs gombra.
  3. A Kulcs létrehozva panel jelenik meg a teljes titkos kulccsal és ezzel a figyelmeztetéssel: „Most látod utoljára a teljes kulcsot – másold ki, és tárold biztonságosan. Többé nem jeleníthető meg.” Használd a Másolás gombot.

Ezt követően a lista csak a kulcs 14 karakteres előtagját mutatja, pontok után, valamint az „utoljára használva” dátumot és a létrehozás dátumát. A titkos kulcsokat SHA-256 hashként tároljuk, sosem nyílt szövegként, így nincs mód egy kulcs visszaállítására – helyette hozz létre egy új kulcsot. A Visszavonás azonnal érvényteleníti a kulcsot: „Minden ügynök, amely ezt a kulcsot használja, azonnal elveszti a hozzáférést. Ez nem vonható vissza.”

A kulcsok így néznek ki: omk_live_<43 base64url chars>. Ugyanezen az oldalon található még a Bekötött alkalmazások lista is – ez az OAuth megfelelője azoknak a klienseknek, amelyek képesek böngészős hozzájárulási folyamatot futtatni: „Azok az alkalmazások, amelyeket a Csatlakoztatás gombbal jóváhagytál. A fiókod nevében járnak el, amíg le nem választod őket.”

A végpont

POST https://<your-host>/mcp
Authorization: Bearer omk_live_…

Az átvitel streamable HTTP, és állapotmentes – a szerver minden kéréshez új sessiont indít, így GET /mcp és DELETE /mcp egyaránt ezt adja válaszul: 405 method not allowed (stateless). A szerver a következő névvel azonosítja magát: optimonk-popup-builder verzió 1.0.0.

Hitelesítési részletek, amelyekre érdemes kódolni:

  • A bearer tokennek a következővel kell kezdődnie: omk_. Egy omk_at_… előtagot OAuth access tokenként kezel a rendszer, minden mást API-kulcsként.
  • Egy hiányzó, hibás formátumú, visszavont vagy lejárt hitelesítő adat 401 választ kap, egy WWW-Authenticate fejléccel. Ha az OAuth engedélyezve van, ez a challenge egy resource_metadata mutatót tartalmaz (RFC 9728), amely lehetővé teszi, hogy egy erre képes kliens saját maga indítsa el a hozzájárulási folyamatot, ahelyett, hogy kulcsot kérne tőled.
  • Az engedélyezési listán nem szereplő böngészőoldalról érkező kérések 403 választ kapnak.
  • A kéréstörzs legfeljebb 1 MB lehet; a nagyobbak 413 választ kapnak.
  • Ha az API-kulcsos és az OAuth-bejárat is ki van kapcsolva a szerveroldalon, a /mcp erre válaszol: 404 mcp disabled.

Mindkét típusú hitelesítő adat ugyanazt a négy scope-ot hordozza: build:read, build:write, campaign:read, campaign:write. A Beállítások felületen létrehozott kulcs a teljes készletet megkapja. Hívd meg a whoami eszközt először – ez visszaadja a fiók azonosítóját, a hitelesítő adat címkéjét, a scope-okat és a canPublish-t, amely megkülönbözteti az „object not found” hibát a „a hitelesítő adat rossz fiókra mutat” esettől.

Mit tudnak az eszközök

26 eszköz áll rendelkezésre. Feladat szerint csoportosítva:

  • Identitás: whoami.
  • Build: build_popup, get_build_status, watch_build, upload_reference_image, get_popup_html, get_popup_preview.
  • Iteráció: edit_popup, patch_popup, restore_revision.
  • Design beszélgetés: start_design_thread, send_design_message, get_design_thread, get_concept_board, select_variant.
  • Kampány: list_campaigns, get_campaign, create_campaign, set_campaign_name, get_campaign_settings, set_campaign_settings, publish_campaign.
  • Kuponok: get_coupon, set_coupon.
  • Jobok: get_job, watch_job.

build_popup egy nyilvánosan elérhető PNG/JPG/WEBP fájlt és a célbolt hosztnevét fogadja, és egy runId-t ad vissza. A buildek aszinkronok: pollozó ciklus helyett használd inkább a watch_build eszközt (megvárja a végét, és közben folyamatjelző értesítéseket küld), a get_build_status-t pedig egyetlen olvasáshoz, vagy olyan klienshez, amely nem tud nyitva tartani egy kérést. interrupted nem végállapot – a futás folytatódik; ezt hibaként kezelni a leggyakoribb hiba ezen a felületen.

create_campaign DRAFT kampányt hoz létre, és designer-session által támogatott buildet igényel: start_design_thread hoz létre egyet, egy önálló build_popup futás nem. publish_campaign publikálja az OptiMonkba, és aktiválja a kampányt.

Mire nem használható

  • Nem az analitikai vagy feliratkozói API. Nincs eszköz jelentésekhez, leadekhez vagy beküldésekhez – a fentebb felsorolt eszközlista a teljes felület.
  • Nem tud ESP/CRM integrációkat beállítani. Nincs olyan eszköz, amely Klaviyo-t, Mailchimpet vagy webhookot csatlakoztatna; ez csak a felületen keresztül, a kampányközpontban lehetséges.
  • Nem tudja kezelni a fiókot. Nincs felhasználó-, domain-, számlázási vagy API-kulcs-kezelés; a kulcs- és a connected-app végpontok szándékosan cookie-alapú hitelesítést használnak, így egy hitelesítő adat sosem tudja felsorolni vagy visszavonni a testvéreit.
  • Ne csak a HTTP státuszkód alapján dönts. Az MCP eszközök visszautasításai – beleértve a scope hibákat és az elfogyott költségvetéseket is – isError: true formában jönnek vissza, szöveggel a content mezőben, egy JSON-RPC HTTP 200 válaszon belül. Ezek nem használják a REST típusos hibaformátumot vagy a rate-limit fejléceket.
  • Ne próbálkozz vakon újra egy időtúllépéses build esetén. Add át az idempotencyKey paramétert a build_popup eszköznek (a REST megfelelője egy Idempotency-Key fejléc, amelyet a rendszer fiókonként 24 órán át figyelembe vesz); egy azonos kulccsal végzett újrapróbálkozás az első futást adja vissza, így nem kell egy második generálásért fizetned.

Szkriptelnél inkább, egy ügynök helyett?

Ugyanazok a hitelesítő adatok működnek egy OpenAPI 3.1 dokumentummal leírt REST felület ellen is. A GET /.well-known/openapi.json és a GET /llms.txt egyaránt olvasható hitelesítő adat nélkül. A REST hibák típusosak (type + code + request_id – ezek alapján dönts, ne a message alapján); a rate-limitelt válaszok X-RateLimit-Limit, X-RateLimit-Remaining és X-RateLimit-Reset fejlécet hordoznak, a költségvetési visszautasítás pedig 429 válasz Retry-After fejléccel.