# API-kulcsok és az MCP-végpont az OptiMonkban

Canonical URL: https://support.optimonk.com/hu/articles/api-keys-and-the-mcp-endpoint

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.