Preskočiť na obsah
API dokumentácia

MCP pre AI asistentov

Server MCP (Model Context Protocol) dovolí AI asistentovi pracovať v účte Poštárne: hľadať a upravovať kontakty, zakladať zoznamy a segmenty, písať šablóny, pripraviť a poslať kampaň, stavať automatizácie a čítať štatistiky. Asistent pracuje s rovnakými pravidlami ako API.

Adresa servera: https://www.postarna.cz/mcp (rovnaká pre všetky firmy; firmu vyberiete pri povolení prístupu).

Pripojenie

ChatGPT

  1. Zapnite režim vývojára: Settings › Apps & Connectors › Advanced settings › Developer mode (platené plány; názvy ponúk sa v ChatGPT menia).
  2. V Apps & Connectors zvoľte Create, názov Poštárna, adresa servera vyššie, overenie OAuth.
  3. ChatGPT vás presmeruje do Poštárne: prihláste sa, vyberte firmu a prístup a povoľte ho.
  4. V novom chate zapnite konektor Poštárna a napíšte, čo má urobiť.

Claude

  1. Settings › Connectors › Add custom connector (vo firemných plánoch pridáva konektor vlastník organizácie).
  2. Názov Poštárna, adresa servera vyššie; OAuth Client ID a Secret nechajte prázdne, Claude sa zaregistruje sám.
  3. Connect, prihlásenie do Poštárne, výber firmy a prístupu, povolenie.

Ďalší klienti

  • Klienti s OAuth (Claude Code, Cursor, VS Code ...) potrebujú len adresu: napríklad claude mcp add --transport http postarna https://www.postarna.cz/mcp.
  • Klient, ktorý vie len hlavičku: API kľúč v Authorization: Bearer pst_... (kľúč s prístupom read alebo full).

Prístup a rozsahy

  • Plný prístup (full): všetko, čo dovolí rola člena, ktorý prístup povolil.
  • Len na čítanie (read): len operácie s úrovňou read; zápis vráti 403 forbidden / scope. Takéto pripojenie nič nezmení ani neodošle.
  • Členov, pozvánky, API kľúče a pripojené aplikácie asistent nikdy nespravuje.
  • Odpojenie: Nastavenia › Dátové zdroje › AI asistenti › Pripojené aplikácie › Odpojiť (alebo odobratie konektora v klientovi). Pripojenie skončí aj odchodom člena z firmy.

Nástroje

Každý nástroj zodpovedá jednej trase API v1 (argumenty pod názvami z API, výsledok JSON). Zoznamy vracajú {items, total, page, pageSize, hasMore, nextPage}.

  • Účet: get_account, list_shops, get_dashboard, search, list_notifications.
  • Kontakty: search_contacts, get_contact, create_contact, update_contact, unsubscribe_contact, delete_contact, erase_contact, blacklist_contact, list_suppressions a ďalšie.
  • Zoznamy, vlastné polia, účely, segmenty, šablóny, kampane, automatizácie, formuláre, importy, štatistiky, kupóny a nastavenia e-shopu.
  • Všeobecné: list_api_endpoints (všetky trasy, ktoré token smie volať), call_api (ktorákoľvek z nich) a get_api_reference (kontrakt API).

V skupine referencií má každá operácia, ktorú nástroj obaľuje, v OpenAPI pole x-mcp-tool s názvom nástroja.

Potvrdenie pred nevratnou akciou

Operácie, ktoré posielajú skutočným ľuďom alebo mažú dáta (v OpenAPI x-mcp-confirm), nástroj nevykoná hneď:

  1. Prvé volanie vráti náhľad {preview: true, confirmRequired: true, action, effect, details, confirm, expiresAt}: komu, koľko, čo sa stane.
  2. Asistent náhľad ukáže človeku a až po jeho súhlase zavolá rovnaký nástroj s rovnakými argumentmi a confirm = token z náhľadu.
  3. Token platí 15 minút a len pre presne to volanie a stav, ktorý náhľad ukázal. Keď sa kampaň, automatizácia alebo počty medzitým zmenia, prijde nový náhľad.

Týka sa to schválenia a obnovenia kampane, zapnutia automatizácie, ručného pridania kontaktov a uvoľnenia čakajúcich, každého mazania, odhlásenia a výmazu kontaktu, kontaktu so súhlasom, odvolania súhlasu, odobratia zo zoznamu a importu. Rovnaký krok majú zmeny, ktoré spustia zapnutú automatizáciu (pridanie do zoznamu, objednávka, úprava šablóny, ktorú automatizácia posiela, udalosť kontaktu, zmena sledovaného poľa, uloženie bežiaceho grafu). Odosielacie trasy sa dajú volať len ich vlastným nástrojom, call_api ich odmietne.

Protokol (pre vývojárov klientov)

  • Streamable HTTP, verzia 2025-11-25 (prijme aj 2025-06-18 a 2025-03-26), jeden koncový bod POST /mcp, JSON-RPC 2.0, dávka najviac 20 správ. Server je bezstavový (GET a DELETE /mcp vracia 405).
  • Bez platného tokenu 401 s WWW-Authenticate: Bearer resource_metadata="https://www.postarna.cz/.well-known/oauth-protected-resource/mcp".
  • OAuth 2.1: dynamická registrácia POST /oauth/register, autorizácia s PKCE S256 GET /oauth/authorize, tokeny POST /oauth/token (prístupový pso_... 1 hodinu, obnovovací psr_... 30 dní s rotáciou), odvolanie POST /oauth/revoke. Metadáta: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.
  • Limit 300 správ JSON-RPC za minútu na token (429 s Retry-After: 60).
  • Každé volanie nástroja sa zapíše do historie účtu s názvom aplikácie (bez argumentov a osobných údajov).