Macaly Cloud MCP Server - Macaly Documentation

Macaly Cloud je MCP server, který z Macaly dělá infrastrukturu pro vašeho vlastního AI agenta. Váš agent píše každý řádek kódu; Macaly poskytuje git repozitář, cloudový sandbox, databázi a platformní schopnosti, build, sdílitelný náhled a produkční hosting na macaly.app. Nic nevzniká na vašem počítači a agent Macaly se vůbec nespustí. Aplikace žije ve vašem workspacu v Macaly od prvního souboru, takže ji kdykoli otevřete v editoru Macaly a pokračujete v práci tam.

Co budete potřebovat

Budete potřebovat MCP klienta, který podporuje vzdálené servery přes Streamable HTTP - Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot nebo Codex.

Připojte svého klienta

Claude, ChatGPT, Cursor a Grok Bot instalují Macaly Cloud ze svých oficiálních adresářů. V Macaly najdete v Nastavení → Propojení kartu pro každý z nich se stejným postupem a odkazem na záznam v adresáři. Ostatní klienti přidají server na adrese:

https://www.macaly.com/api/cloud/mcp

V obou případech klient otevře okno prohlížeče, ve kterém se přihlásíte do Macaly a schválíte přístup (OAuth). Žádné klíče kopírovat nemusíte.

Otevřete stránku Macaly Cloud v adresáři konektorů Claude. Funguje na claude.ai, v desktopové aplikaci i na mobilu.
Klikněte na Connect.
Přihlaste se do Macaly a schvalte přístup v okně, které se otevře.

Spusťte v terminálu:

claude mcp add macaly-cloud --transport http https://www.macaly.com/api/cloud/mcp

Pak spusťte Claude Code a příkazem /mcp se přihlaste do Macaly.

Otevřete plugin Macaly Cloud na Cursor Marketplace a přidejte ho. Můžete také spustit /add-plugin macaly-code v chatu Cursoru.
Když Cursor otevře prohlížeč, přihlaste se do Macaly a schvalte přístup.

Spusťte v terminálu:

codex mcp add macaly-cloud --url https://www.macaly.com/api/cloud/mcp
codex mcp login macaly-cloud

Přihlášení pomocí API klíče

Místo OAuth se můžete autentizovat API klíčem Macaly - hodí se pro headless agenty a automatizaci. Klíč předejte jako bearer token:

{
  "mcpServers": {
    "macaly-cloud": {
      "url": "https://www.macaly.com/api/cloud/mcp",
      "headers": {
        "Authorization": "Bearer macaly_your_api_key_here"
      }
    }
  }
}

API klíče jsou vázané na jeden workspace, takže nástroje s parametrem teamId si ho doplní samy.

Postavte aplikaci od začátku do konce

Vytvořte aplikaci

Váš agent zavolá create_app s názvem. Zpět dostane chatId a briefing projektu. Aplikace vznikne prázdná - žádný úvodní prompt, žádný AI build.

Napište kód

write_file zapíše celý soubor a edit_file nahradí přesný text v existujícím souboru, takže malá změna velkého souboru nemusí znovu posílat celý soubor. Každé volání write_file, edit_file a delete_file je jeden atomický git commit s vlastním záznamem v historii aplikace. První zápis do studeného workspacu trvá o ~20-30 sekund déle, než se sandbox nastartuje.

Přidejte platformní schopnosti

U databáze, plateb, AI, médií nebo vyhledávání si agent přečte návod přes skill_info a spustí jeho příkazy pomocí bash - sandbox už má přihlašovací údaje, které návody potřebují.

Zkontrolujte typy

Po posledním zápisu agent spustí bash ".sandbox/check-errors --strict" - zachytí typové, stylové i serverové chyby naráz, na konci vypíše shrnutí výsledku a skončí chybou, když selže TypeScript nebo CSS. Při selhání vrátí get_logs skutečný výstup.

Náhled

Náhled se přebuilduje automaticky pár vteřin po posledním zápisu. Jakmile build projde, preview_app vrátí živou URL k otevření nebo sdílení. S parametrem path odkaz rovnou otevře podstránku, například /pricing. Agent volá preview_app na konci každého tahu, ve kterém aplikaci změnil, i když je dřívější odkaz stále platný - tímto voláním dává Macaly vědět, že tah skončil.

Publikujte

Až výslovně řeknete, že chcete jít do provozu, agent zavolá publish_app a dotazuje se get_deployment s vráceným deploymentId, dokud stav není READY. Pak vám předá liveUrl, adresu verze, která je právě živá. connect_domain připojí vlastní doménu nebo přejmenuje subdoménu Macaly.

Dostupné nástroje

Macaly Cloud nabízí 20 nástrojů.

Workspacy a aplikace

Nástroj	Co dělá
`list_teams`	Vypíše workspacy, ve kterých můžete stavět
`create_app`	Vytvoří novou prázdnou aplikaci na výchozím stacku a vrátí její briefing
`list_projects`	Vypíše aplikace workspacu od naposledy upravených, s hledáním a stránkováním. Připnuté aplikace se vrátí na první stránce
`get_project`	Přehled stavu: stav buildu náhledu, URL náhledu, stav nejnovějšího publikování a `liveUrl`, briefing a kdo právě na aplikaci pracuje
`get_messages`	Přečte historii chatu aplikace - co bylo zadáno a co už je postavené - než začne měnit
`duplicate_app`	Naklonuje aplikaci i s historií do nové

Kód

Nástroj	Co dělá
`list_files`	Vypíše zdrojové soubory aplikace
`read_file`	Přečte jeden soubor podle cesty, nebo jen rozsah řádků pomocí `startLine` a `endLine`
`write_file`	Zapíše celý soubor a hned ho commitne
`edit_file`	Nahradí přesný text v existujícím souboru a hned ho commitne - až 20 náhrad v jednom volání, provedou se všechny, nebo žádná
`delete_file`	Smaže soubor a smazání hned commitne
`bash`	Spustí příkaz v sandboxu aplikace - instalace, CLI, skripty skillů a typovou kontrolu `.sandbox/check-errors --strict`. Příkaz může mít až 32 000 znaků a běžet až 240 sekund

Média

Nástroj	Co dělá
`upload_file`	Přidá soubor do knihovny médií aplikace a vrátí jeho trvalou veřejnou URL (až 1 GB). Soubor přijde z veřejně dostupné URL, nebo z vašeho počítače či ze sandboxu aplikace přes připravený příkaz `curl`
`list_media`	Vypíše soubory v knihovně médií aplikace s jejich veřejnými URL a vrátí odkaz, kam můžete přetáhnout místní soubor

Žádný nástroj nepřijímá surové bajty souboru. U souboru na vašem počítači vrátí upload_file příkaz curl, který agent spustí ve vašem vlastním shellu. U souboru, který agent vytvořil v sandboxu, spustí příkaz v sandboxu. Pokud váš agent shell nemá, přetáhněte soubor do knihovny médií přes odkaz z list_media.

Vygenerované nebo stažené obrázky, audio a video nedávejte do složky public/ aplikace. Každý build náhledu nahrává public/ znovu, takže mnoho souborů nebo velké soubory build zpomalí a mohou způsobit jeho selhání. Média nahrajte přes upload_file a použijte vrácenou URL.

Schopnosti a diagnostika

Nástroj	Co dělá
`skill_info`	Načte návod k platformní schopnosti s hotovými příkazy a vzory kódu
`get_logs`	Stáhne logy buildu, dev serveru nebo nasazení
`preview_app`	Vrátí tříhodinový odkaz na náhled ke sdílení, volitelně na podstránku

Publikování

Nástroj	Co dělá
`publish_app`	Publikuje aplikaci do produkce na její `macaly.app` URL
`get_deployment`	Zjistí stav nejnovějšího pokusu o publikování (nebo pokusu podle `deploymentId`), `liveUrl` a připojené domény
`connect_domain`	Připojí vlastní doménu nebo přejmenuje subdoménu Macaly

Cloudové akce

Cloudové akce jsou to, co váš externí agent dělá přes Macaly Cloud. Plán Zdarma zahrnuje 100 cloudových akcí měsíčně. Placené plány nemají měsíční limit cloudových akcí. Tyto akce se počítají:

Vytvoření nebo duplikace aplikace (create_app, duplicate_app)
Zápis, úprava nebo smazání souborů (write_file, edit_file, delete_file)
Spouštění příkazů (bash)
Nahrávání souborů (upload_file)
Publikování (publish_app)
Připojení domény (connect_domain)

Čtení souborů (read_file), výpisy a náhledy (preview_app) jsou zdarma. Chatování s vlastním agentem Macaly v aplikaci cloudové akce nespotřebovává. Limit plánu Zdarma sdílí celý workspace, obnovuje se 1. dne každého měsíce (UTC) a nepřevádí se. Po jeho vyčerpání se další započítávané akce odmítnou a zobrazí se datum obnovení a odkaz do Fakturace. Čtení, aplikace, které už jsou live, a chatování s Macaly v aplikaci dál fungují. Fakturace a Nastavení → Využití a limity ukazují, kolik cloudových akcí jste použili. Viz Využití a limity.

Souběh s editorem Macaly

Aplikace postavená přes Macaly Cloud je běžná aplikace Macaly. Můžete ji otevřít v editoru, prohlédnout si historii verzí, vrátit se zpět nebo pokračovat s agentem Macaly.

Každá změna se zaznamenává. Ke každému zápisu patří krátké vysvětlení od vašeho agenta, které se objeví v historii chatu jako karta s názvem klienta, který změnu provedl - takže agent Macaly má kontext, pokud budete pokračovat tam. Když běh s více změnami skončí, karta shrne, co se změnilo.
Můžete se vrátit. Tlačítkem Obnovit předchozí verzi na kartě vrátíte aplikaci do stavu po daném běhu. Z chatu se tím smaže vše, co následovalo. Tlačítkem Duplikovat tuto verzi zkopírujete do nového projektu.
Jedna karta za každý tah. Macaly nevidí vaše zprávy agentovi, jen jeho volání nástrojů. Běh skončí, když vám agent předá aplikaci přes preview_app nebo publish_app. Pokud toto volání vynechá, může se více vašich požadavků ocitnout v jedné kartě.
Vždy jen jeden agent. Zatímco pracuje váš externí agent, je chat zamčený: agent Macaly nezačne svůj tah a v okně pro psaní uvidíte, kdo aplikaci právě drží. Zámek se sám uvolní pár minut po posledním zápisu, nebo hned jakmile vám agent ukáže náhled.
Náhled čeká na hotovou aplikaci. Buildy uprostřed práce se zadržují, takže panel náhledu ukazuje aplikaci, kterou jste měli, dokud běh neskončí.

Ukázkové prompty

Postav mi aplikaci na Macaly: landing page pro předplatné kávy
s hero sekcí, ceníkem a formulářem pro sběr e-mailů.

Přidej do mé kávové aplikace na Macaly přepínač tmavého režimu,
zkontroluj typy a pošli mi odkaz na náhled.

Nastav mé kávové aplikaci databázi a ukládej do ní přihlášené e-maily.

Publikuj kávovou aplikaci a připoj doménu coffee.example.com.

Řešení potíží

Neobjeví se přihlašovací okno

Ověřte, že váš klient podporuje vzdálené MCP servery s OAuth a že jste zadali celou URL včetně cesty /api/cloud/mcp.

Zápis vrací CHAT_CLAIMED_BY_AGENT nebo CHAT_CLAIMED_BY_EDITOR

Aplikaci právě drží někdo jiný: buď je uprostřed tahu agent Macaly, nebo do ní nedávno zapisoval jiný externí editor. Počkejte a zkuste to znovu - zámek se sám uvolní pár minut po poslední aktivitě.

Build náhledu selže na vypršení času při nahrávání

Výstup buildu je příliš velký nebo má příliš mnoho souborů, obvykle kvůli médiím v public/. get_logs s log_type: "build" ukáže počet souborů a jejich velikost. Přesuňte média z public/ přes upload_file, použijte vrácené URL a nechte náhled znovu přebuildovat.

URL náhledu zatím nic neukazuje

Náhledy se servírují z dokončeného buildu. Zkontrolujte previewBuildStatus přes get_project a při selhání si přečtěte get_logs s log_type: "build".

Akce je odmítnuta, protože jsem vyčerpal/a cloudové akce

Plán Zdarma zahrnuje 100 cloudových akcí měsíčně. Zpráva o odmítnutí ukazuje datum, kdy se obnoví (1. dne v měsíci, UTC), a odkaz do Fakturace. Čtení a náhledy dál fungují. Měsíční limit odstraníte přechodem na Starter nebo Pro.

Nástroj vrací FORBIDDEN

Buď má workspace, ve kterém pracujete, Macaly Cloud vypnutý, nebo akce vyžaduje funkci plánu, kterou nemáte - třeba publikování na vlastní doménu.

Stále si nevíte rady? Ozvěte se přes chat v Macaly nebo mrkněte do FAQ.

​Co budete potřebovat

​Připojte svého klienta

​Přihlášení pomocí API klíče

​Postavte aplikaci od začátku do konce

​Dostupné nástroje

​Workspacy a aplikace

​Kód

​Média

​Schopnosti a diagnostika

​Publikování

​Cloudové akce

​Souběh s editorem Macaly

​Ukázkové prompty

​Řešení potíží

Co budete potřebovat

Připojte svého klienta

Přihlášení pomocí API klíče

Postavte aplikaci od začátku do konce

Dostupné nástroje

Workspacy a aplikace

Kód

Média

Schopnosti a diagnostika

Publikování

Cloudové akce

Souběh s editorem Macaly

Ukázkové prompty

Řešení potíží