Přeskočit na obsah
API dokumentace

MCP pro AI asistenty

Server MCP (Model Context Protocol) dovolí AI asistentovi pracovat v účtu Poštárny: hledat a upravovat kontakty, zakládat seznamy a segmenty, psát šablony, připravit a poslat kampaň, stavět automatizace a číst statistiky. Asistent pracuje se stejnými pravidly jako API.

Adresa serveru: https://www.postarna.cz/mcp (stejná pro všechny firmy; firmu vyberete při povolení přístupu).

Připojení

ChatGPT

  1. Zapněte režim vývojáře: Settings › Apps & Connectors › Advanced settings › Developer mode (placené plány; názvy nabídek se v ChatGPT mění).
  2. V Apps & Connectors zvolte Create, název Poštárna, adresa serveru výše, ověření OAuth.
  3. ChatGPT vás přesměruje do Poštárny: přihlaste se, vyberte firmu a přístup a povolte ho.
  4. V novém chatu zapněte konektor Poštárna a napište, co má udělat.

Claude

  1. Settings › Connectors › Add custom connector (ve firemních plánech přidává konektor vlastník organizace).
  2. Název Poštárna, adresa serveru výše; OAuth Client ID a Secret nechte prázdné, Claude se zaregistruje sám.
  3. Connect, přihlášení do Poštárny, výběr firmy a přístupu, povolení.

Další klienti

  • Klienti s OAuth (Claude Code, Cursor, VS Code ...) potřebují jen adresu: například claude mcp add --transport http postarna https://www.postarna.cz/mcp.
  • Klient, který umí jen hlavičku: API klíč v Authorization: Bearer pst_... (klíč s přístupem read nebo full).

Přístup a rozsahy

  • Plný přístup (full): vše, co dovolí role člena, který přístup povolil.
  • Jen čtení (read): jen operace s úrovní read; zápis vrátí 403 forbidden / scope. Takové připojení nic nezmění ani neodešle.
  • Členy, pozvánky, API klíče a připojené aplikace asistent nikdy nespravuje.
  • Odpojení: Nastavení › Datové zdroje › AI asistenti › Připojené aplikace › Odpojit (nebo odebrání konektoru v klientovi). Připojení skončí i odchodem člena z firmy.

Nástroje

Každý nástroj odpovídá jedné trase API v1 (argumenty pod názvy z API, výsledek JSON). Seznamy vracejí {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 další.
  • Seznamy, vlastní pole, účely, segmenty, šablony, kampaně, automatizace, formuláře, importy, statistiky, kupóny a nastavení e-shopu.
  • Obecné: list_api_endpoints (všechny trasy, které token smí volat), call_api (libovolná z nich) a get_api_reference (kontrakt API).

Ve skupině referencí má každá operace, kterou nástroj obaluje, v OpenAPI pole x-mcp-tool s názvem nástroje.

Potvrzení před nevratnou akcí

Operace, které posílají skutečným lidem nebo mažou data (v OpenAPI x-mcp-confirm), nástroj neprovede hned:

  1. První volání vrátí náhled {preview: true, confirmRequired: true, action, effect, details, confirm, expiresAt}: komu, kolik, co se stane.
  2. Asistent náhled ukáže člověku a teprve po jeho souhlasu zavolá stejný nástroj se stejnými argumenty a confirm = token z náhledu.
  3. Token platí 15 minut a jen pro přesně to volání a stav, který náhled ukázal. Když se kampaň, automatizace nebo počty mezitím změní, přijde nový náhled.

Týká se to schválení a obnovení kampaně, zapnutí automatizace, ručního přidání kontaktů a uvolnění čekajících, každého mazání, odhlášení a výmazu kontaktu, kontaktu se souhlasem, odvolání souhlasu, odebrání ze seznamu a importu. Stejný krok mají změny, které spustí zapnutou automatizaci (přidání do seznamu, objednávka, úprava šablony, kterou automatizace posílá, událost kontaktu, změna sledovaného pole, uložení běžícího grafu). Odesílací trasy jde volat jen jejich vlastním nástrojem, call_api je odmítne.

Protokol (pro vývojáře klientů)

  • Streamable HTTP, verze 2025-11-25 (přijme i 2025-06-18 a 2025-03-26), jeden koncový bod POST /mcp, JSON-RPC 2.0, dávka nejvýš 20 zpráv. Server je bezstavový (GET a DELETE /mcp vrací 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á registrace POST /oauth/register, autorizace s PKCE S256 GET /oauth/authorize, tokeny POST /oauth/token (přístupový pso_... 1 hodina, obnovovací psr_... 30 dní s rotací), odvolání POST /oauth/revoke. Metadata: /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.
  • Limit 300 zpráv JSON-RPC za minutu na token (429 s Retry-After: 60).
  • Každé volání nástroje se zapíše do historie účtu s názvem aplikace (bez argumentů a osobních údajů).