> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Macaly MCP Server

> Ovládejte Macaly z Claude, Cursoru, ChatGPT a dalších AI agentů

Macaly MCP server umožňuje AI agentům programově spravovat vaše aplikace v Macaly pomocí [Model Context Protocol](https://modelcontextprotocol.io) — otevřeného standardu pro připojení AI asistentů k externím nástrojům. Stačí ho připojit jednou a agent pak může vytvářet aplikace, žádat o změny, kontrolovat vygenerovaný kód a publikovat do produkce, to vše přímo z konverzace.

Jde o opak ostatních integrací Macaly: místo aby agent Macaly sahal do vašich nástrojů, sahá externí agent (Claude, Cursor, ChatGPT, …) do Macaly.

<Callout icon="user">
  Dostupné v plánu Pro. Každý workspace, ve kterém přes MCP server pracujete, musí být na plánu Pro — viz [Funkce a limity plánů](#funkce-a-limity-planu).
</Callout>

## Proč připojit MCP server

* **Stavějte aplikace ze svého oblíbeného AI klienta.** Popište aplikaci v Claude nebo Cursoru a agent ji vytvoří v Macaly, počká na build a předá vám odkaz na náhled.
* **Iterujte bez přepínání nástrojů.** Žádejte o změny, sledujte stav buildu a kontrolujte, co se změnilo — přímo z chatu, ve kterém už jste.
* **Nahlédněte do vygenerovaného kódu.** Vypište soubory, čtěte zdrojáky, zobrazte diff libovolné úpravy a vraťte se ke starší verzi, pokud se něco pokazilo.
* **Publikujte, až když řeknete.** Publikování je samostatný, explicitní krok. Agent může aplikaci nasadit do provozu a připojit vlastní doménu — ale jen když o to požádáte.

## Co budete potřebovat

* **Workspace Macaly na plánu Pro** — MCP server je funkce plánu Pro
* MCP klienta, který podporuje vzdálené servery přes Streamable HTTP, například Claude (claude.ai a Desktop), Claude Code, Cursor, ChatGPT nebo VS Code

## Připojte svého klienta

Server je dostupný na adrese:

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

Když ho přidáte, klient otevře okno prohlížeče, ve kterém se přihlásíte do Macaly a schválíte přístup (OAuth). To je vše — žádné klíče ke kopírování.

<Tabs>
  <Tab title="Claude">
    1. Na [claude.ai](https://claude.ai) nebo v desktopové aplikaci Claude otevřete **Settings → Connectors**.
    2. Klikněte na **Add custom connector**.
    3. Zadejte `https://www.macaly.com/api/mcp/mcp` a klikněte na **Add**.
    4. Klikněte na **Connect** a schvalte přístup v okně Macaly, které se otevře.
  </Tab>

  <Tab title="Claude Code">
    Spusťte v terminálu:

    ```bash theme={null}
    claude mcp add --transport http macaly https://www.macaly.com/api/mcp/mcp
    ```

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

  <Tab title="Cursor">
    Přidejte server do `.cursor/mcp.json` (pro projekt) nebo `~/.cursor/mcp.json` (globálně):

    ```json theme={null}
    {
      "mcpServers": {
        "macaly": {
          "url": "https://www.macaly.com/api/mcp/mcp"
        }
      }
    }
    ```

    Cursor vás vyzve k přihlášení do Macaly při prvním použití některého nástroje.
  </Tab>

  <Tab title="ChatGPT">
    1. Otevřete **Settings → Connectors** (vyžaduje režim pro vývojáře nebo plán s vlastními konektory).
    2. Klikněte na **Create** a zadejte `https://www.macaly.com/api/mcp/mcp`.
    3. Schvalte přístup v okně Macaly, které se otevře.
  </Tab>

  <Tab title="VS Code">
    Přidejte server do `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "macaly": {
          "type": "http",
          "url": "https://www.macaly.com/api/mcp/mcp"
        }
      }
    }
    ```

    VS Code vás provede přihlášením při prvním spuštění serveru.
  </Tab>
</Tabs>

<Tip>
  Po připojení přes OAuth můžete pracovat v libovolném workspace, jehož jste členem. Nejdřív požádejte agenta, aby „vypsal moje týmy v Macaly" — většina nástrojů přijímá `teamId`, aby agent věděl, kde má pracovat.
</Tip>

### Použití API klíče místo OAuth

V **plánech Enterprise** se můžete místo OAuth ověřit pomocí [API klíče Macaly](/docs/cs/api/authentication) — hodí se pro headless agenty a automatizaci. Klíč předejte jako bearer token:

```json theme={null}
{
  "mcpServers": {
    "macaly": {
      "url": "https://www.macaly.com/api/mcp/mcp",
      "headers": {
        "Authorization": "Bearer macaly_your_api_key_here"
      }
    }
  }
}
```

API klíče jsou vázané na jeden workspace, takže nástroje, které přijímají `teamId`, si ho zjistí automaticky.

## Dostupné nástroje

### Workspacy a kredity

| Nástroj      | Co dělá                                                                           |
| ------------ | --------------------------------------------------------------------------------- |
| `list_teams` | Vypíše workspacy, ve kterých můžete pracovat, včetně vaší role a zůstatku kreditů |
| `get_usage`  | Zjistí zůstatek kreditů workspace, plán a přibližný počet zbývajících zpráv       |

### Aplikace

| Nástroj         | Co dělá                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| `create_app`    | Vytvoří novou aplikaci z promptu (volitelně s přílohami — obrázky nebo soubory) a spustí první build |
| `list_projects` | Vypíše aplikace ve workspace, s vyhledáváním a stránkováním                                          |
| `get_project`   | Vrátí metadata jedné aplikace: název, framework, stav nasazení, screenshot                           |
| `rename_app`    | Změní název aplikace                                                                                 |
| `duplicate_app` | Vytvoří kopii aplikace (včetně historie) jako novou aplikaci, na které můžete pracovat nezávisle     |
| `delete_app`    | Přesune aplikaci do koše (publikované aplikace je nejdřív potřeba stáhnout z produkce)               |

### Build a iterace

| Nástroj            | Co dělá                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `send_message`     | Požádá o změnu existující aplikace, jako navazující zpráva v chatu Macaly  |
| `get_messages`     | Přečte historii konverzace aplikace                                        |
| `get_build_status` | Zjistí stav aktuálního buildu                                              |
| `wait_for_build`   | Počká (na straně serveru), dokud build neskončí nebo nevyprší časový limit |

### Kontrola kódu

| Nástroj          | Co dělá                                                              |
| ---------------- | -------------------------------------------------------------------- |
| `list_files`     | Vypíše vygenerované zdrojové soubory aplikace                        |
| `read_file`      | Přečte jeden zdrojový soubor podle cesty                             |
| `list_edits`     | Vypíše historii úprav aplikace — každý tah AI, který vytvořil commit |
| `get_diff`       | Vrátí unified diff dané úpravy                                       |
| `revert_to_edit` | Vrátí aplikaci k dřívější úpravě                                     |

### Publikování a domény

| Nástroj          | Co dělá                                                                               |
| ---------------- | ------------------------------------------------------------------------------------- |
| `publish_app`    | Publikuje aplikaci do produkce — volá se jen tehdy, když o nasazení výslovně požádáte |
| `get_deployment` | Vrátí stav nasazení, produkční URL a připojené domény                                 |
| `list_domains`   | Vypíše vlastní domény registrované ve workspace                                       |
| `connect_domain` | Připojí vlastní doménu k publikované aplikaci (vrátí DNS záznamy k nastavení)         |

Buildy jsou asynchronní: `create_app` a `send_message` vrátí odpověď okamžitě a agent pak pomocí `wait_for_build` nebo `get_build_status` sleduje build, dokud neskončí. Build aplikaci **nepublikuje** — aplikace si můžete plně prohlédnout v náhledu, než jdou do provozu.

## Média ve vygenerovaných aplikacích

Aplikace postavené přes MCP server mohou obsahovat **obrázky vygenerované AI jako designové prvky** — hlavní vizuály, ilustrace, textury pozadí, favicony — stejně jako je agent Macaly vytváří v editoru. K dispozici je i vyhledávání stock fotek a ikon, takže aplikace může místo toho použít licencované obrázky.

<Warning>
  **Generování AI zvuku a AI videa přes MCP server dostupné není.** Generování hudby, syntéza řeči (text-to-speech) a generování videa jsou pro buildy spuštěné z připojeného klienta vypnuté. Konektor tím odpovídá pravidlům pro generování médií v adresářích AI klientů, přes které je distribuovaný.
</Warning>

Když o ně přesto požádáte, agent aplikaci postaví bez nich, místo aby build selhal — landing page například dostane statický hero obrázek místo vygenerovaného videa na pozadí. **Přepis řeči na text** zůstává dostupný, protože zvuk analyzuje, ne generuje.

Omezení platí jen pro buildy spuštěné přes MCP server. Když pracujete přímo v Macaly, generování hudby, namluvení i videa funguje běžným způsobem na plánech, které je zahrnují.

## Postavte aplikaci od začátku do konce

<Steps>
  <Step title="Vytvořte">
    Požádejte agenta, aby něco postavil. Zavolá `create_app` s vaším popisem a dostane zpět ID aplikace.
  </Step>

  <Step title="Počkejte na build">
    Agent volá `wait_for_build`, dokud build neskončí — obvykle pár minut, u složitějších aplikací déle.
  </Step>

  <Step title="Iterujte">
    Žádejte o změny běžným jazykem. Každá se promění ve volání `send_message` následované dalším buildem. Pomocí `get_diff` zkontrolujete, co přesně se změnilo.
  </Step>

  <Step title="Publikujte">
    Až budete spokojeni, požádejte o nasazení. Agent zavolá `publish_app` a pak kontroluje `get_deployment`, dokud není URL vaší aplikace připravená.
  </Step>
</Steps>

## Ukázkové prompty

```
Vytvoř aplikaci v Macaly: landing page pro předplatné kávy
s hero sekcí, ceníkem a formulářem pro přihlášení k odběru e-mailů.
```

```
Přidej do mé kávové aplikace přepínač tmavého režimu, počkej na
build a ukaž mi diff.
```

```
Po poslední změně se něco rozbilo — ukaž mi historii úprav
a vrať aplikaci k verzi před ní.
```

```
Publikuj aplikaci a připoj doménu coffee.example.com.
```

## Funkce a limity plánů

MCP server je dostupný v **plánu Pro**. Kontrola probíhá pro každý workspace zvlášť: každý workspace, ve kterém nástroj pracuje, musí být na plánu Pro — pokud jste tedy členem několika workspaců, agent může pracovat jen v těch s plánem Pro. `list_teams` funguje vždy, takže agent zjistí, ve kterých vašich workspacech může pracovat.

Volání nástroje ve workspace, který není na plánu Pro, vrátí chybu `FORBIDDEN` s vysvětlením, že plán MCP server nezahrnuje.

Požadavky jsou limitované na účet: **120 čtecích volání** a **20 zapisovacích volání** za minutu. Při překročení limitu nástroj vrátí chybu `RATE_LIMITED` s dobou čekání a slušně se chovající agenti automaticky zpomalí.

## Oprávnění a bezpečnost

<Warning>
  Připojený klient jedná **vaším jménem**. Vidí každý workspace, jehož jste členem, a buildy, které spustí, spotřebovávají skutečné kredity — stejně jako když pracujete v editoru Macaly sami.
</Warning>

* **Buildy stojí kredity.** Každé volání `create_app` a `send_message` spotřebuje kredity z workspace, ve kterém běží. Zůstatky zkontrolujete pomocí `get_usage`.
* **Publikování nikdy neproběhne automaticky.** Server instruuje agenty, aby `publish_app` volali jen tehdy, když o nasazení výslovně požádáte.
* **Destruktivní akce jsou označené.** `delete_app` a `revert_to_edit` jsou označené jako destruktivní, takže většina klientů si nejdřív vyžádá potvrzení. Smazání publikované aplikace přes MCP je zcela zablokované — nejdřív ji stáhněte z produkce.
* **Buildy se dostanou na veřejný web.** Když si to zadání vyžádá, build agent vyhledává na internetu, stahuje stránky, dělá screenshoty a scrapuje veřejná data. Proto jsou `create_app` a `send_message` označené jako open-world a klienti na to mohou upozornit ještě před spuštěním.
* **Svůj účet máte pod kontrolou.** Server můžete kdykoli odpojit v nastavení konektorů svého klienta a tím mu odebrat přístup.

## Řešení problémů

* **Okno pro přihlášení se neobjeví:** ujistěte se, že váš klient podporuje vzdálené MCP servery s OAuth a že jste přidali celou URL včetně cesty `/api/mcp/mcp`.
* **Nástroj vrací FORBIDDEN:** workspace, ve kterém pracujete, není na plánu Pro (MCP server vyžaduje plán Pro), nebo předáváte `teamId` workspace, jehož nejste členem.
* **`wait_for_build` vyprší:** u větších buildů je to normální — build běží dál a agent prostě zavolá `wait_for_build` znovu a čeká dál.
* **Potřebujete pomoc?** Ozvěte se přes chat v Macaly nebo se podívejte do [FAQ](/docs/cs/welcome/faq).