Copy page

MCP

MCP dokumentace

MCP server Zaslat propojuje libovolného AI asistenta (Claude, ChatGPT, n8n i vlastní agenty) přímo se Zaslat. Asistent pak umí porovnávat ceny dopravců, zakládat a rušit zásilky, sledovat je a tisknout štítky – vše přirozeným jazykem.

Proč MCP

Zaslat tradičně nabízí dvě rozhraní: webovou aplikaci pro lidi a REST API pro systémy. MCP je to třetí – vytvořené pro AI asistenty, kteří jednají jménem konkrétního uživatele.

Na rozdíl od REST API, které vyžaduje formální integraci a zapojení vývojáře, pokrývá MCP mezikroky, které dosud spadaly „mezi" obě rozhraní:

• zpracování adres v různých formátech z tabulek,
• převod objednávek z prostého textu e-mailu na zásilky,
• rychlé dotazy na cenu dopravy,
• jednorázové úkoly, jako je objednání svozu nebo opětovný tisk štítku, bez proklikávání aplikace.

MCP míří na technicky zvídavé uživatele a provozní týmy, které chtějí automatizovat expedici bez velkého integračního projektu. Funguje s libovolným asistentem podporujícím MCP – rozumí kontextu uživatele a respektuje jeho preference, například výchozí adresu odesílatele nebo oblíbené dopravce.

Rychlý start

Postup pro Claude.ai nebo Claude Desktop:

1. Přejděte do Settings → Connectors → Add custom connector.
2. Zadejte URL: https://mcp.zaslat.cz/mcp
3. Zvolte ověření přes OAuth (budete přesměrováni na přihlášení do Zaslat).
4. Potvrďte přístup – tím je nastavení dokončeno.

Ověření

Server ověřuje přihlašovací údaje proti backendu Zaslat při inicializaci a poté je znovu ověřuje každých 30 minut po celou dobu trvání MCP relace.

OAuth 2.1 (doporučeno)

Server zveřejňuje metadata autorizace na adrese:

Code
GET https://mcp.zaslat.cz/.well-known/oauth-protected-resource

MCP klienti si autorizační server zjistí automaticky a provedou standardní authorization-code flow s PKCE proti api.zaslat.cz.

Požadované rozsahy oprávnění (scopes):

• rates
• shipments:read
• shipments:write

API klíč

Bezobslužní klienti (n8n, skripty, vlastní agenti) předávají API klíč Zaslat v hlavičce X-ApiKey:

Code
POST /mcp HTTP/1.1
Host: mcp.zaslat.cz
X-ApiKey: <vas-api-klic>
Content-Type: application/json

API klíč si vygenerujete po přihlášení v aplikaci app.zaslat.cz v sekci Nastavení → Integrace → API integrace.

Nástroje

MCP server nabízí patnáct nástrojů rozdělených do několika kategorií. Nástroje označené jako pouze čtení nijak nemění vaše data.

Ceny a informace

Nástroj	Popis	Mění data
get_rates	Porovná ceny dopravců pro danou trasu a seznam balíků.	Ne
get_profile	Načte profil uživatele, výchozí adresu odesílatele a nastavení účtu.	Ne
search_parcel_points	Vyhledá nejbližší výdejní / podací místa podle adresy, PSČ nebo dopravce.	Ne

Správa zásilek

Nástroj	Popis	Mění data
create_shipment	Založí novou zásilku (Home2Home, Shop2Home, Home2Shop, Shop2Shop).	Ano
cancel_shipment	Zruší zásilku, kterou dopravce dosud nevyzvedl.	Ano

Přehled a sledování

Nástroj	Popis	Mění data
list_shipments	Vypíše zásilky s filtry a stránkováním.	Ne
get_shipment_detail	Kompletní detail zásilky včetně sledovacího čísla dopravce.	Ne
track_shipment	Stav sledování s historií událostí.	Ne

E-commerce integrace

Nástroj	Popis	Mění data
list_integrations	Vypíše napojené e-shopové integrace (Shopify, Upgates, eBay, …) a jejich stav.	Ne
run_integration_sync	Spustí import nových objednávek ze všech aktivních integrací do košíku zásilek.	Ano
get_integration_logs	Vrátí poslední záznamy logu dané integrace (výsledky importu, chyby).	Ne

Košík (rozpracované zásilky)

Košík obsahuje zásilky připravené k objednání — například importované z e-shopových integrací. Nic v košíku není objednáno ani účtováno, dokud zásilky závazně neodešlete.

Nástroj	Popis	Mění data
list_shipment_drafts	Vypíše rozpracované zásilky v košíku.	Ne
update_shipment_draft	Upraví rozpracovanou zásilku: rozměry a hmotnost balíků, dopravce, datum svozu, referenční číslo nebo adresy. Zásilka zůstává v košíku neobjednaná.	Ano
submit_shipment_drafts	Závazně objedná vybrané zásilky z košíku (zpoplatněná operace), volitelně včetně objednání svozu kurýrem.	Ano

Štítky

Nástroj	Popis	Mění data
print_label	Vygeneruje přepravní štítek (odkaz na PDF nebo base64).	Ne

Typický pracovní postup

1. get_profile – načtení výchozí adresy odesílatele.
2. get_rates – porovnání cen dopravců.
3. search_parcel_points – vyhledání výdejního místa (Home2Shop / Shop2Shop).
4. create_shipment – založení zásilky u vybraného dopravce.
5. print_label – stažení štítku k tisku.
6. track_shipment – sledování stavu zásilky.

Pro e-shopy s napojenou integrací:

1. run_integration_sync – import nových objednávek z e-shopu do košíku.
2. list_shipment_drafts – kontrola importovaných zásilek.
3. update_shipment_draft – doplnění rozměrů, změna dopravce či opravy adres.
4. submit_shipment_drafts – závazné objednání vybraných zásilek.
5. print_label – tisk štítků.

Ukázkové dotazy

Porovnání cen

• „Jaké jsou ceny dopravy pro balík 30×20×15 cm, 3 kg z Prahy do Brna?"
• „Porovnej ceny dopravců pro zásilku 5 kg do Bratislavy."
• „Kolik stojí poslat 2 balíky z Ostravy do Berlína?"

Založení zásilky

• „Pošli balík přes DPD Janu Novákovi, Příčná 5, Brno 602 00, 2 kg."
• „Vytvoř zásilku Zásilkovnou na výdejní místo 12345, příjemce Eva Malá, telefon 777123456."
• „Objednej PPL s dobírkou 500 Kč na účet 1234567890/0100."

Sledování a přehled

• „Kde je moje zásilka IZ123456?"
• „Zobraz mi posledních 10 zásilek."
• „Najdi všechny nedoručené zásilky DPD z minulého týdne."
• „Ukaž mi zásilky s nezaplacenou dobírkou za poslední měsíc."

Štítky

• „Vytiskni štítek pro zásilku IZ123456."
• „Potřebuji štítek A6 pro termotiskárnu."

Hromadné odesílání

• „(nahrání souboru Excel) Pošli všechny zásilky z tohoto souboru přes DPD."

E-shop a košík

• „Stáhni nové objednávky z mého e-shopu."
• „Ukaž mi, co mám v košíku."
• „Změň u zásilky pro pana Nováka dopravce na DPD."
• „Objednej všechny zásilky v košíku a rovnou objednej i svoz na zítra."
• „Proč se včera nenaimportovaly objednávky ze Shopify?"

Zrušení

• „Zruš zásilku IZ123456."

Výchozí hodnoty a konvence

• Výchozí rozměr balíku: pokud rozměry neuvedete, použije se 20 × 20 × 20 cm, 1 kg. U FedEx a UPS vždy uvádějte přesné rozměry – každý centimetr ovlivňuje cenu.
• ID zásilek: zásilky Zaslat používají formát IZxxxxx (např. IZ123456). Liší se od sledovacího čísla dopravce – to získáte pomocí get_shipment_detail.
• Kódy zemí: ISO 3166-1 alpha-2 (CZ, SK, DE).
• PSČ: bez mezer (60200, nikoli 602 00).

Podpora

• E-mail: admin@zaslat.cz