Macaly Cloud MCP Sunucusu - Macaly Documentation

Macaly Cloud, Macaly’yi kendi yapay zeka kodlama agent’ınızın arkasındaki altyapıya dönüştüren bir MCP sunucusudur. Kodun her satırını agent’ınız yazar; Macaly ise git deposunu, bulut sandbox’ını, veritabanını ve platform yeteneklerini, derlemeyi, paylaşılabilir önizlemeyi ve macaly.app üzerinde üretim barındırmasını sağlar. Bilgisayarınızda hiçbir şey üretilmez ve Macaly’nin kendi agent’ı hiç çalışmaz. Uygulama ilk dosyadan itibaren Macaly workspace’inizde yaşar; istediğiniz zaman Macaly editöründe açıp oradan devam edebilirsiniz.

Gerekenler

Streamable HTTP üzerinden uzak sunucuları destekleyen bir MCP istemcisine ihtiyacınız var: Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot veya Codex.

İstemcinizi bağlayın

Claude, ChatGPT, Cursor ve Grok Bot, Macaly Cloud’u resmî dizinlerinden yükler. Macaly’de Ayarlar → Bağlantılar bölümünde her biri için aynı adımları ve dizin kaydına giden bağlantıyı içeren bir kart bulunur. Diğer istemciler sunucuyu şu adresten ekler:

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

Her iki durumda da istemciniz bir tarayıcı penceresi açar; orada Macaly’ye giriş yapar ve erişimi onaylarsınız (OAuth). Kopyalanacak anahtar yoktur.

Claude bağlayıcı dizinindeki Macaly Cloud sayfasını açın. claude.ai’de, masaüstü uygulamasında ve mobilde çalışır.
Connect’e tıklayın.
Açılan pencerede Macaly’ye giriş yapın ve erişimi onaylayın.

Terminalinizde çalıştırın:

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

Ardından Claude Code’u başlatın ve Macaly’ye giriş yapmak için /mcp komutunu çalıştırın.

Cursor Marketplace’teki Macaly Cloud pluginini açın ve ekleyin. Cursor sohbetinde /add-plugin macaly-code komutunu da çalıştırabilirsiniz.
Cursor tarayıcınızı açtığında Macaly’ye giriş yapın ve erişimi onaylayın.

Terminalinizde çalıştırın:

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

Bunun yerine API anahtarı kullanma

OAuth yerine bir Macaly API anahtarıyla kimlik doğrulayabilirsiniz; bu, arayüzsüz agent’lar ve otomasyon için kullanışlıdır. Anahtarı bearer token olarak gönderin:

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

API anahtarları tek bir workspace’e bağlıdır, bu yüzden teamId alan araçlar bunu kendileri belirler.

Baştan sona bir uygulama inşa edin

Uygulamayı oluşturun

Agent’ınız bir adla create_app çağırır. Karşılığında bir chatId ve proje brifingi alır. Uygulama boş oluşturulur: başlangıç istemi yok, yapay zeka derlemesi yok.

Kodu yazın

write_file bir dosyayı tümüyle yazar, edit_file ise mevcut bir dosyadaki birebir metni değiştirir; böylece büyük bir dosyadaki küçük bir değişiklik için dosyanın tamamı yeniden gönderilmez. Her write_file, edit_file ve delete_file çağrısı, uygulamanın geçmişinde kendi kaydı olan atomik bir git commit’idir. Soğuk bir workspace’e ilk yazma, sandbox açılırken ~20-30 saniye daha uzun sürer.

Platform yeteneklerini ekleyin

Veritabanı, ödemeler, yapay zeka, medya veya arama için agent, kılavuzu skill_info ile okur ve komutlarını bash ile çalıştırır - sandbox, kılavuzların ihtiyaç duyduğu kimlik bilgilerini zaten içerir.

Tipleri denetleyin

Son yazmadan sonra agent bash ".sandbox/check-errors --strict" çalıştırır - bu, tip, stil ve sunucu hatalarını tek seferde yakalar, sonunda bir sonuç özeti verir ve TypeScript veya CSS başarısız olduğunda hatayla çıkar. Hata olursa get_logs gerçek çıktıyı verir.

Önizleyin

Önizleme, son yazmadan birkaç saniye sonra otomatik olarak yeniden derlenir. Derleme başarılı olduğunda preview_app, açmanız veya paylaşmanız için canlı URL’yi döndürür. path ile bağlantı doğrudan bir alt sayfayı açar, örneğin /pricing. Agent, uygulamayı değiştiren her turun sonunda, önceki bir bağlantı hâlâ geçerli olsa bile preview_app çağırır - bu çağrı Macaly’ye turun bittiğini bildirir.

Yayınlayın

Açıkça yayına almak istediğinizde agent publish_app çağırır ve durum READY olana kadar dönen deploymentId ile get_deployment sorgular. Ardından size canlıdaki sürümün adresi olan liveUrl değerini verir. connect_domain, özel bir alan adı bağlar veya Macaly alt alan adını yeniden adlandırır.

Kullanılabilir araçlar

Macaly Cloud 20 araç sunar.

Workspace’ler ve uygulamalar

Araç	Ne yapar
`list_teams`	İnşa edebileceğiniz workspace’leri listeler
`create_app`	Varsayılan yığında yeni ve boş bir uygulama oluşturur ve brifingini döndürür
`list_projects`	Bir workspace’in uygulamalarını en son güncellenenden başlayarak, arama ve sayfalamayla listeler. Sabitlenmiş uygulamalar ilk sayfada gelir
`get_project`	Durum özeti: önizleme derleme durumu, önizleme URL’si, en son yayınlama durumu ve `liveUrl`, brifing ve uygulama üzerinde kimin çalıştığı
`get_messages`	Değişiklik yapmadan önce uygulamanın sohbet geçmişini okur - ne istendiğini ve şimdiye dek ne inşa edildiğini
`duplicate_app`	Bir uygulamayı geçmişiyle birlikte yenisine kopyalar

Kod

Araç	Ne yapar
`list_files`	Uygulamanın kaynak dosyalarını listeler
`read_file`	Yola göre tek bir dosyayı ya da `startLine` ve `endLine` ile yalnızca bir satır aralığını okur
`write_file`	Bir dosyayı tümüyle yazar ve hemen commit’ler
`edit_file`	Mevcut bir dosyadaki birebir metni değiştirir ve hemen commit’ler - çağrı başına en fazla 20 değiştirme; ya hepsi uygulanır ya hiçbiri
`delete_file`	Bir dosyayı siler ve silmeyi hemen commit’ler
`bash`	Uygulamanın sandbox’ında kabuk komutu çalıştırır - kurulumlar, CLI’lar, skill betikleri ve `.sandbox/check-errors --strict` tip denetimi. Bir komut en fazla 32.000 karakter olabilir ve en fazla 240 saniye çalışabilir

Medya

Araç	Ne yapar
`upload_file`	Uygulamanın medya kitaplığına bir dosya ekler ve kalıcı genel URL’sini döndürür (1 GB’a kadar). Dosya herkese açık bir URL’den ya da hazır bir `curl` komutuyla bilgisayarınızdan veya uygulamanın sandbox’ından gelir
`list_media`	Uygulamanın medya kitaplığındaki dosyaları genel URL’leriyle listeler ve yerel bir dosyayı bırakabileceğiniz bir bağlantı verir

Hiçbir araç ham dosya baytlarını kabul etmez. Bilgisayarınızdaki bir dosya için upload_file, agent’ınızın kendi kabuğunuzda çalıştıracağı bir curl komutu döndürür. Agent’ın sandbox’ta oluşturduğu bir dosya için agent komutu sandbox’ta çalıştırır. Agent’ınızın kabuğu yoksa dosyayı list_media bağlantısıyla medya kitaplığına bırakın.

Oluşturulan veya indirilen görselleri, sesleri ve videoları uygulamanın public/ klasörüne koymayın. Her önizleme derlemesi public/ klasörünü yeniden yükler; bu yüzden çok sayıda veya büyük dosya derlemeyi yavaşlatır ve başarısız olmasına yol açabilir. Medyayı upload_file ile yükleyin ve döndürülen URL’yi kullanın.

Yetenekler ve tanılama

Araç	Ne yapar
`skill_info`	Bir platform yeteneğinin kılavuzunu, çalıştırmaya hazır komutlar ve uygulanacak kod kalıplarıyla okur
`get_logs`	Derleme, geliştirme sunucusu veya dağıtım günlüklerini getirir
`preview_app`	Paylaşmanız için üç saat geçerli bir önizleme bağlantısı döndürür; isteğe bağlı olarak bir alt sayfa için

Yayınlama

Araç	Ne yapar
`publish_app`	Uygulamayı `macaly.app` URL’sinde üretime yayınlar
`get_deployment`	En son yayınlama denemesini (veya `deploymentId` ile belirli birini), `liveUrl` değerini ve bağlı alan adlarını denetler
`connect_domain`	Özel bir alan adı bağlar veya Macaly alt alan adını yeniden adlandırır

Cloud eylemleri

Cloud eylemleri, harici agent’ınızın Macaly Cloud üzerinden yaptığı işlemlerdir. Ücretsiz plan ayda 100 Cloud eylemi içerir. Ücretli planlarda aylık Cloud eylemi limiti yoktur. Şu eylemler sayılır:

Bir uygulama oluşturmak veya çoğaltmak (create_app, duplicate_app)
Dosya yazmak, düzenlemek veya silmek (write_file, edit_file, delete_file)
Komut çalıştırmak (bash)
Dosya yüklemek (upload_file)
Yayınlamak (publish_app)
Bir alan adı bağlamak (connect_domain)

Dosya okuma (read_file), listeleme ve önizlemeler (preview_app) ücretsizdir. Uygulamanın içinde Macaly’nin kendi agent’ıyla sohbet etmek Cloud eylemi kullanmaz. Ücretsiz plandaki hak çalışma alanının tamamı tarafından paylaşılır, her ayın 1’inde (UTC) sıfırlanır ve sonraki aya devretmez. Hak bittiğinde sayılan diğer eylemler, sıfırlanma tarihi ve Faturalandırma sayfasına bir bağlantıyla birlikte reddedilir. Okumalar, zaten yayında olan uygulamalar ve uygulamanın içinde Macaly ile sohbet etme çalışmaya devam eder. Faturalandırma ve Ayarlar → Kullanım ve Sınırlar kaç Cloud eylemi kullandığınızı gösterir. Bkz. Kullanım ve Sınırlar.

Macaly editörüyle birlikte çalışma

Macaly Cloud ile inşa edilen bir uygulama sıradan bir Macaly uygulamasıdır. Editörde açabilir, sürüm geçmişine bakabilir, geri alabilir veya Macaly’nin kendi agent’ıyla devam edebilirsiniz.

Her değişiklik kaydedilir. Her yazma, agent’ınızdan kısa bir açıklama taşır; bu açıklama sohbet geçmişinde, değişikliği yapan istemcinin adını taşıyan bir kart olarak görünür - böylece orada devam ederseniz Macaly’nin agent’ı bağlamı bilir. Birkaç değişiklik içeren bir oturum bittiğinde kartı nelerin değiştiğini özetler.
Geri dönebilirsiniz. Uygulamayı o oturumdan sonraki hâline döndürmek için karttaki Önceki sürümü geri yükle düğmesine tıklayın. Bu, sohbette ondan sonraki her şeyi kaldırır. Çoğalt ise o sürümü yeni bir projeye kopyalar.
Her tur için tek kart. Macaly, agent’ınıza yazdığınız mesajları görmez, yalnızca araç çağrılarını görür. Bir oturum, agent’ınız uygulamayı preview_app veya publish_app ile teslim ettiğinde biter. Agent bu çağrıyı atlarsa birkaç isteğiniz tek bir kartta toplanabilir.
Aynı anda tek agent. Harici agent’ınız çalışırken sohbet kilitlidir: Macaly’nin agent’ı bir tur başlatmaz ve yazma alanı uygulamanın kimde olduğunu gösterir. Kilit, son yazmadan birkaç dakika sonra kendiliğinden açılır ya da agent’ınız size önizlemeyi gösterir göstermez kalkar.
Önizleme bitmiş uygulamayı bekler. Ara derlemeler bekletilir, böylece önizleme paneli oturum bitene kadar zaten sahip olduğunuz uygulamayı göstermeye devam eder.

Örnek istemler

Bana Macaly'de bir uygulama yap: kahve aboneliği için hero bölümü,
fiyatlandırma ve e-posta kayıt formu olan bir açılış sayfası.

Macaly'deki kahve uygulamama koyu mod anahtarı ekle, tipleri denetle
ve bana önizleme bağlantısını ver.

Kahve uygulamam için bir veritabanı kur ve e-posta kayıtlarını orada sakla.

Kahve uygulamasını yayınla ve coffee.example.com alan adını bağla.

Sorun giderme

Giriş penceresi açılmıyor

İstemcinizin OAuth ile uzak MCP sunucularını desteklediğinden ve /api/cloud/mcp yolu dahil tam URL’yi girdiğinizden emin olun.

Bir yazma CHAT_CLAIMED_BY_AGENT veya CHAT_CLAIMED_BY_EDITOR döndürüyor

Uygulama başkasında: ya Macaly’nin agent’ı bir turun ortasında ya da başka bir harici editör kısa süre önce yazdı. Bekleyip yeniden deneyin - kilit, son etkinlikten birkaç dakika sonra kendiliğinden açılır.

Önizleme derlemesi yükleme zaman aşımıyla başarısız oluyor

Derleme çıktısı çok büyük ya da çok fazla dosya içeriyor; bunun sebebi genellikle public/ içindeki medyadır. log_type: "build" ile get_logs, dosya sayısını ve boyutunu gösterir. Medyayı upload_file ile public/ dışına taşıyın, döndürülen URL’leri kullanın ve önizlemenin yeniden derlenmesini bekleyin.

Önizleme URL'si henüz bir şey göstermiyor

Önizlemeler tamamlanmış bir derlemeden sunulur. get_project ile previewBuildStatus durumunu kontrol edin; başarısızsa log_type: "build" ile get_logs çıktısını okuyun.

Cloud eylemlerim bittiği için bir eylem reddediliyor

Ücretsiz plan ayda 100 Cloud eylemi içerir. Ret mesajı, hakkın sıfırlanacağı tarihi (ayın 1’i, UTC) ve Faturalandırma sayfasına bir bağlantıyı gösterir. Okumalar ve önizlemeler çalışmaya devam eder. Aylık limiti kaldırmak için Starter veya Pro planına yükseltin.

Bir araç FORBIDDEN döndürüyor

Ya çalıştığınız workspace’te Macaly Cloud kapalıdır ya da işlem, sahip olmadığınız bir plan özelliği gerektirir - örneğin özel bir alan adında yayınlamak.

Hâlâ takıldınız mı? Macaly içindeki sohbetten bize ulaşın veya SSS sayfasına bakın.

​Gerekenler

​İstemcinizi bağlayın

​Bunun yerine API anahtarı kullanma

​Baştan sona bir uygulama inşa edin

​Kullanılabilir araçlar

​Workspace’ler ve uygulamalar

​Kod

​Medya

​Yetenekler ve tanılama

​Yayınlama

​Cloud eylemleri

​Macaly editörüyle birlikte çalışma

​Örnek istemler

​Sorun giderme

Gerekenler

İstemcinizi bağlayın

Bunun yerine API anahtarı kullanma

Baştan sona bir uygulama inşa edin

Kullanılabilir araçlar

Workspace’ler ve uygulamalar

Kod

Medya

Yetenekler ve tanılama

Yayınlama

Cloud eylemleri

Macaly editörüyle birlikte çalışma

Örnek istemler

Sorun giderme