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, milyen protokollt használ a végpont, és hol vannak a korlátai. Kulcs létrehozásához lásd: MCP-hitelesítés és hozzáférés az OptiMonkban.

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.

A scope-okról és a whoami eszközről lásd: MCP-hitelesítés és hozzáférés az OptiMonkban.

Mit tudnak az eszközök

Az összes eszközt az MCP-eszközök referenciája az OptiMonk szerverhez cikkben találod.

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 – az MCP-eszközök referenciájában felsorolt eszközök jelentik a teljes felületet.

  • 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.