> ## 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 Cloud MCP Server
> Anna Clauden, ChatGPT:n, Cursorin, Grok Botin tai Codexin kirjoittaa koodi, niin Macaly ajaa, rakentaa ja hostaa sen
Macaly Cloud on [MCP](https://modelcontextprotocol.io) -palvelin, joka tekee Macalysta oman tekoälykoodausagenttisi infrastruktuurin. Agenttisi kirjoittaa jokaisen koodirivin, ja Macaly tarjoaa git-repositorion, pilvisandboxin, tietokannan ja alustan ominaisuudet, buildin, jaettavan esikatselun sekä tuotantohostauksen osoitteessa `macaly.app`.
Mitään ei synny omalle koneellesi, eikä Macalyn oma agentti käynnisty lainkaan. Sovellus on Macaly-workspacessasi ensimmäisestä tiedostosta alkaen, joten voit avata sen Macalyn editorissa milloin tahansa ja jatkaa rakentamista siellä.
## Mitä tarvitset
Tarvitset MCP-asiakasohjelman, joka tukee etäpalvelimia Streamable HTTP -yhteydellä: Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot tai Codex.
## Yhdistä asiakasohjelmasi
Claude, ChatGPT, Cursor ja Grok Bot asentavat Macaly Cloudin omista virallisista hakemistoistaan. Macalyn kohdassa **Asetukset → Yhteydet** on jokaiselle niistä oma kortti, jossa on samat vaiheet ja linkki hakemistomerkintään. Muut asiakasohjelmat lisäävät palvelimen osoitteesta:
```
https://www.macaly.com/api/cloud/mcp
```
Kummassakin tapauksessa asiakasohjelmasi avaa selainikkunan, jossa kirjaudut Macalyyn ja hyväksyt pääsyn (OAuth). Avaimia ei tarvitse kopioida.
1. Avaa [Macaly Cloud -merkintä](https://claude.ai/directory/macaly-cloud) Clauden liitännäishakemistossa. Se toimii claude.ai:ssa, työpöytäsovelluksessa ja mobiilissa.
2. Klikkaa **Connect**.
3. Kirjaudu Macalyyn ja hyväksy pääsy avautuvassa ikkunassa.
Suorita päätteessä:
```bash theme={null}
claude mcp add macaly-cloud --transport http https://www.macaly.com/api/cloud/mcp
```
Käynnistä sitten Claude Code ja kirjaudu Macalyyn komennolla `/mcp`.
1. Avaa [Macaly Cloud -lisäosa](https://chatgpt.com/plugins/plugin_asdk_app_6a732e22122c8191ac404137c0514300) ChatGPT:n lisäosahakemistossa. Sama lisäosa toimii selaimessa ja työpöytäsovelluksessa.
2. Klikkaa **Install**.
3. Kun ChatGPT pyytää yhdistämään tilisi, kirjaudu Macalyyn ja hyväksy pääsy avautuvassa ikkunassa.
1. Avaa [Macaly Cloud -lisäosa](https://cursor.com/marketplace/macaly) Cursor Marketplacessa ja lisää se. Voit myös suorittaa Cursorin keskustelussa komennon `/add-plugin macaly-code`.
2. Kun Cursor avaa selaimesi, kirjaudu Macalyyn ja hyväksy pääsy.
1. Valitse Grok Botissa sivupalkista **Plugins**. Mobiilisovelluksessa napauta avatariasi ja valitse **Plugins**.
2. Etsi **Macaly Cloud** ja lisää se.
3. Kun Grok Bot pyytää sinua painamaan **Authorize**, kirjaudu Macalyyn ja hyväksy pääsy selaimessa.
4. Varmista, että lisäosa näkyy kohdassa **Installed**. Sen jälkeen se on käytettävissä jokaisessa ajamassasi Botissa.
Suorita päätteessä:
```bash theme={null}
codex mcp add macaly-cloud --url https://www.macaly.com/api/cloud/mcp
codex mcp login macaly-cloud
```
### API-avaimen käyttö OAuthin sijaan
Voit tunnistautua [Macalyn API-avaimella](/docs/fi/api/authentication) OAuthin sijaan. Tämä sopii päätteettömille agenteille ja automaatioon. Välitä avain bearer-tokenina:
```json theme={null}
{
"mcpServers": {
"macaly-cloud": {
"url": "https://www.macaly.com/api/cloud/mcp",
"headers": {
"Authorization": "Bearer macaly_your_api_key_here"
}
}
}
}
```
API-avaimet rajautuvat yhteen workspaceen, joten `teamId`-parametrin ottavat työkalut selvittävät sen automaattisesti.
## Rakenna sovellus alusta loppuun
Agenttisi kutsuu `create_app`-työkalua nimellä. Vastauksena se saa `chatId`:n ja projektin ohjeistuksen. Sovellus luodaan tyhjänä, ilman aloituskehotetta ja ilman tekoälyrakennusta.
`write_file` kirjoittaa kokonaisen tiedoston, ja `edit_file` korvaa tarkan tekstin olemassa olevassa tiedostossa, joten pientä muutosta suureen tiedostoon varten koko tiedostoa ei tarvitse lähettää uudelleen. Jokainen `write_file`-, `edit_file`- ja `delete_file`-kutsu on yksi atominen git-commit, jolla on oma merkintänsä sovelluksen historiassa. Ensimmäinen kirjoitus kylmässä workspacessa kestää noin 20–30 sekuntia pidempään, kun sandbox vielä käynnistyy.
Tietokantaa, maksuja, tekoälyä, mediaa tai hakua varten agentti lukee oppaan `skill_info`-työkalulla ja ajaa sen komennot `bash`-työkalulla. Sandboxissa on jo oppaiden tarvitsemat tunnistetiedot.
Viimeisen kirjoituksen jälkeen agentti ajaa komennon `bash ".sandbox/check-errors --strict"`, joka löytää tyyppi-, tyyli- ja palvelinvirheet yhdellä kertaa, näyttää lopuksi yhteenvedon tuloksista ja päättyy virheeseen, jos TypeScript- tai CSS-tarkistus epäonnistuu. Jos tarkistus epäonnistuu, `get_logs` palauttaa todellisen tulosteen.
Esikatselu rakentuu uudelleen automaattisesti muutaman sekunnin kuluttua viimeisestä kirjoituksesta. Kun rakennus onnistuu, `preview_app` palauttaa julkisen osoitteen, jonka voit avata tai jakaa. `path`-parametrin avulla linkki avaa suoraan alasivun, esimerkiksi `/pricing`. Agentti kutsuu `preview_app`-työkalua jokaisen sellaisen vuoron lopussa, jossa se muutti sovellusta, myös silloin, kun aiempi linkki on yhä voimassa. Tämä kutsu kertoo Macalylle, että vuoro on päättynyt.
Kun pyydät erikseen julkaisemaan, agentti kutsuu `publish_app`-työkalua ja kyselee `get_deployment`-työkalulta palautetulla `deploymentId`:llä, kunnes tila on `READY`. Sen jälkeen se antaa sinulle `liveUrl`:n eli julkaistun version osoitteen. `connect_domain` liittää oman verkkotunnuksen tai nimeää Macaly-aliverkkotunnuksen uudelleen.
## Käytettävissä olevat työkalut
Macaly Cloud tarjoaa 20 työkalua.
### Workspacet ja sovellukset
| Työkalu | Mitä se tekee |
| - | - |
| `list_teams` | Listaa workspacet, joissa voit rakentaa |
| `create_app` | Luo uuden, tyhjän sovelluksen oletusalustalle ja palauttaa sen ohjeistuksen |
| `list_projects` | Listaa workspacen sovellukset viimeksi päivitetyt ensin, hakua ja sivutusta tukien. Kiinnitetyt sovellukset palautetaan ensimmäisellä sivulla |
| `get_project` | Tilannekuva: esikatselun rakennustila, esikatselun osoite, uusimman julkaisun tila ja `liveUrl`, ohjeistus sekä se, kuka sovelluksen parissa parhaillaan työskentelee |
| `get_messages` | Lukee sovelluksen keskusteluhistorian (mitä on pyydetty ja rakennettu tähän mennessä) ennen muutosten tekemistä |
| `duplicate_app` | Kopioi sovelluksen historioineen uudeksi sovellukseksi |
### Koodi
| Työkalu | Mitä se tekee |
| - | - |
| `list_files` | Listaa sovelluksen lähdetiedostot |
| `read_file` | Lukee yhden tiedoston polun perusteella tai vain osan sen riveistä parametreilla `startLine` ja `endLine` |
| `write_file` | Kirjoittaa yhden tiedoston kokonaan ja commitoi sen heti |
| `edit_file` | Korvaa tarkan tekstin olemassa olevassa tiedostossa ja commitoi sen heti. Yhdessä kutsussa voi olla enintään 20 korvausta, ja ne tehdään joko kaikki tai ei yhtään |
| `delete_file` | Poistaa yhden tiedoston ja commitoi poiston heti |
| `bash` | Ajaa shell-komennon sovelluksen sandboxissa: asennukset, CLI-työkalut, skill-skriptit ja `.sandbox/check-errors --strict`-tyyppitarkistus. Komennossa voi olla enintään 32 000 merkkiä, ja se voi olla käynnissä enintään 240 sekuntia |
### Media
| Työkalu | Mitä se tekee |
| - | - |
| `upload_file` | Lisää tiedoston sovelluksen mediakirjastoon ja palauttaa sen pysyvän julkisen osoitteen (enintään 1 Gt). Tiedosto tulee julkisesti saatavilla olevasta osoitteesta tai valmiin `curl`-komennon avulla omalta koneeltasi tai sovelluksen sandboxista |
| `list_media` | Listaa sovelluksen mediakirjaston tiedostot julkisine osoitteineen ja antaa linkin, jonka kautta voit pudottaa sinne paikallisen tiedoston |
Mikään työkalu ei ota vastaan raakaa tiedostodataa. Omalla koneellasi olevaa tiedostoa varten `upload_file` palauttaa `curl`-komennon, jonka agenttisi ajaa omassa shellissäsi. Jos agentti on tehnyt tiedoston sandboxissa, se ajaa komennon sandboxissa. Jos agentillasi ei ole shelliä, pudota tiedosto mediakirjastoon `list_media`-työkalun antaman linkin kautta.
Älä tallenna luotuja tai ladattuja kuvia, ääntä tai videota sovelluksen `public/`-kansioon. Jokainen esikatselun build lataa `public/`-kansion uudelleen, joten monet tai suuret tiedostot hidastavat buildia ja voivat saada sen epäonnistumaan. Lataa media `upload_file`-työkalulla ja käytä palautettua osoitetta.
### Ominaisuudet ja diagnostiikka
| Työkalu | Mitä se tekee |
| - | - |
| `skill_info` | Lukee alustan ominaisuuden oppaan, jossa on valmiita komentoja ja sovellettavia koodimalleja |
| `get_logs` | Hakee build-, kehityspalvelin- tai julkaisulokit |
| `preview_app` | Palauttaa kolme tuntia voimassa olevan esikatselulinkin jaettavaksi, valinnaisesti alasivulle |
### Julkaisu
| Työkalu | Mitä se tekee |
| - | - |
| `publish_app` | Julkaisee sovelluksen tuotantoon sen `macaly.app`-osoitteeseen |
| `get_deployment` | Tarkistaa uusimman julkaisuyrityksen (tai `deploymentId`:n mukaisen yrityksen), `liveUrl`:n ja liitetyt verkkotunnukset |
| `connect_domain` | Liittää oman verkkotunnuksen tai nimeää sovelluksen Macaly-aliverkkotunnuksen uudelleen |
## Cloud-toiminnot
Cloud-toiminnot ovat asioita, joita ulkoinen agenttisi tekee Macaly Cloudin kautta. Ilmainen paketti sisältää **100 Cloud-toimintoa kuukaudessa**. Maksullisissa paketeissa ei ole kuukausittaista Cloud-toimintojen rajaa.
Nämä toiminnot lasketaan mukaan:
* Sovelluksen luominen tai monistaminen (`create_app`, `duplicate_app`)
* Tiedostojen kirjoittaminen, muokkaaminen tai poistaminen (`write_file`, `edit_file`, `delete_file`)
* Komentojen ajaminen (`bash`)
* Tiedostojen lataaminen (`upload_file`)
* Julkaiseminen (`publish_app`)
* Verkkotunnuksen liittäminen (`connect_domain`)
Tiedostojen lukeminen (`read_file`), listaukset ja esikatselut (`preview_app`) ovat ilmaisia. Keskustelu Macalyn oman agentin kanssa sovelluksen sisällä ei kuluta Cloud-toimintoja.
Ilmainen kiintiö on koko workspacen yhteinen, nollautuu joka kuun 1. päivä (UTC) eikä siirry eteenpäin. Kun kiintiö on käytetty, uudet laskettavat toiminnot hylätään ja viestissä näkyy nollautumispäivä sekä linkki Laskutus-sivulle. Lukeminen, jo verkossa olevat sovellukset ja keskustelu Macalyn kanssa sovelluksen sisällä toimivat edelleen. Laskutus-sivu ja **Asetukset → Käyttö ja rajat** näyttävät, kuinka monta Cloud-toimintoa olet käyttänyt. Katso [Käyttö ja rajat](/docs/fi/account/workspaces/usage).
## Työskentely Macalyn editorin rinnalla
Macaly Cloudilla rakennettu sovellus on tavallinen Macaly-sovellus. Voit avata sen editorissa, tarkastella versiohistoriaa, palauttaa aiemman version tai jatkaa Macalyn oman agentin kanssa.
* **Jokainen muutos tallentuu.** Jokaiseen kirjoitukseen kuuluu agenttisi lyhyt selitys, joka näkyy sovelluksen keskusteluhistoriassa korttina, jossa mainitaan muutoksen tehnyt asiakasohjelma. Näin Macalyn agentti tietää taustat, jos jatkat myöhemmin siellä. Kun useita muutoksia sisältänyt ajo päättyy, sen kortti kokoaa yhteen, mitä muuttui.
* **Voit palata taaksepäin.** Napsauta kortissa **Palauta edellinen versio**, niin sovellus palaa siihen tilaan, jossa se oli kyseisen ajon jälkeen. Tämä poistaa keskustelusta kaiken sen jälkeisen. **Monista** kopioi kyseisen version uuteen projektiin.
* **Yksi kortti jokaista vuoroa kohden.** Macaly ei näe viestejäsi agentillesi, vain sen työkalukutsut. Ajo päättyy, kun agenttisi luovuttaa sovelluksen sinulle `preview_app`- tai `publish_app`-kutsulla. Jos se jättää kutsun väliin, useampi pyyntösi voi päätyä samaan korttiin.
* **Vain yksi agentti kerrallaan.** Kun ulkoinen agenttisi työskentelee, keskustelu on lukittu: Macalyn agentti ei aloita vuoroa, ja viestikenttä kertoo, kenellä sovellus on. Lukitus vapautuu itsestään muutaman minuutin kuluttua viimeisestä kirjoituksesta tai heti, kun agenttisi näyttää sinulle esikatselun.
* **Esikatselu odottaa valmista sovellusta.** Kesken työn tapahtuvat uudelleenrakennukset pidätetään, joten esikatselupaneeli näyttää aiemman sovelluksesi, kunnes ajo päättyy.
## Esimerkkikehotteita
```
Rakenna minulle Macaly-sovellus: laskeutumissivu kahvitilauspalvelulle,
jossa on hero-osio, hinnoittelu ja sähköpostirekisteröitymislomake.
```
```
Lisää Macalyssa olevaan kahvisovellukseeni tumman tilan kytkin,
tee tyyppitarkistus ja anna minulle esikatselulinkki.
```
```
Ota kahvisovelluksellleni käyttöön tietokanta ja tallenna
sähköpostirekisteröitymiset siihen.
```
```
Julkaise kahvisovellus ja liitä siihen verkkotunnus coffee.example.com.
```
## Vianmääritys
Varmista, että asiakasohjelmasi tukee OAuthia käyttäviä MCP-etäpalvelimia ja että annoit koko osoitteen `/api/cloud/mcp`-polku mukaan lukien.
Sovellus on jonkun muun käytössä: Macalyn oma agentti on kesken vuoron tai toinen ulkoinen editori on kirjoittanut siihen äskettäin. Odota ja yritä uudelleen, sillä lukitus vapautuu itsestään muutaman minuutin kuluttua viimeisestä toiminnasta.
Buildin tulos on liian suuri tai siinä on liikaa tiedostoja, yleensä mediaa `public/`-kansiossa. `get_logs` arvolla `log_type: "build"` näyttää tiedostojen määrän ja koon. Siirrä media pois `public/`-kansiosta `upload_file`-työkalulla, käytä palautettuja osoitteita ja anna esikatselun rakentua uudelleen.
Esikatselut tarjoillaan valmiista buildista. Tarkista `previewBuildStatus` työkalulla `get_project` ja lue `get_logs` arvolla `log_type: "build"`, jos build epäonnistui.
Ilmainen paketti sisältää 100 Cloud-toimintoa kuukaudessa. Hylkäysviestissä näkyy päivä, jolloin ne nollautuvat (kuun 1. päivä, UTC), sekä linkki Laskutus-sivulle. Lukeminen ja esikatselut toimivat edelleen. Päivitä Starter- tai Pro-pakettiin, niin kuukausiraja poistuu.
Joko workspacessa, jossa toimit, Macaly Cloud on poistettu käytöstä, tai toiminto vaatii ominaisuuden, joka ei kuulu pakettiisi, esimerkiksi julkaisun omaan verkkotunnukseen.
Etkö vieläkään pääse eteenpäin? Ota yhteyttä Macalyn keskustelun kautta tai katso [UKK](/docs/fi/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.