Macaly Cloud MCP Server - Macaly Documentation

Macaly Cloud on MCP -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.

Avaa Macaly Cloud -merkintä Clauden liitännäishakemistossa. Se toimii claude.ai:ssa, työpöytäsovelluksessa ja mobiilissa.
Klikkaa Connect.
Kirjaudu Macalyyn ja hyväksy pääsy avautuvassa ikkunassa.

Suorita päätteessä:

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

Käynnistä sitten Claude Code ja kirjaudu Macalyyn komennolla /mcp.

Avaa Macaly Cloud -lisäosa Cursor Marketplacessa ja lisää se. Voit myös suorittaa Cursorin keskustelussa komennon /add-plugin macaly-code.
Kun Cursor avaa selaimesi, kirjaudu Macalyyn ja hyväksy pääsy.

Suorita päätteessä:

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 OAuthin sijaan. Tämä sopii päätteettömille agenteille ja automaatioon. Välitä avain bearer-tokenina:

{
  "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

Luo sovellus

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.

Kirjoita koodi

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.

Lisää alustan ominaisuuksia

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.

Tyyppitarkistus

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

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.

Julkaise

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.

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

Kirjautumisikkuna ei aukea

Varmista, että asiakasohjelmasi tukee OAuthia käyttäviä MCP-etäpalvelimia ja että annoit koko osoitteen /api/cloud/mcp-polku mukaan lukien.

Kirjoitus palauttaa CHAT_CLAIMED_BY_AGENT tai CHAT_CLAIMED_BY_EDITOR

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.

Esikatselun build epäonnistuu latauksen aikakatkaisuun

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.

Esikatseluosoite ei näytä vielä mitään

Esikatselut tarjoillaan valmiista buildista. Tarkista previewBuildStatus työkalulla get_project ja lue get_logs arvolla log_type: "build", jos build epäonnistui.

Toiminto hylätään, koska Cloud-toimintoni on käytetty

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.

Työkalu palauttaa FORBIDDEN

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.

​Mitä tarvitset

​Yhdistä asiakasohjelmasi

​API-avaimen käyttö OAuthin sijaan

​Rakenna sovellus alusta loppuun

​Käytettävissä olevat työkalut

​Workspacet ja sovellukset

​Koodi

​Media

​Ominaisuudet ja diagnostiikka

​Julkaisu

​Cloud-toiminnot

​Työskentely Macalyn editorin rinnalla

​Esimerkkikehotteita

​Vianmääritys

Mitä tarvitset

Yhdistä asiakasohjelmasi

API-avaimen käyttö OAuthin sijaan

Rakenna sovellus alusta loppuun

Käytettävissä olevat työkalut

Workspacet ja sovellukset

Koodi

Media

Ominaisuudet ja diagnostiikka

Julkaisu

Cloud-toiminnot

Työskentely Macalyn editorin rinnalla

Esimerkkikehotteita

Vianmääritys