Servidor MCP do Macaly Cloud - Macaly Documentation

O Macaly Cloud é um servidor MCP que transforma o Macaly na infraestrutura por trás do seu próprio agente de código com IA. O seu agente escreve cada linha de código; o Macaly fornece o repositório git, o sandbox na nuvem, o banco de dados e os recursos da plataforma, o build, a pré-visualização compartilhável e a hospedagem em produção em macaly.app. Nada é gerado no seu computador e o agente do próprio Macaly nunca é executado. O app fica no seu workspace do Macaly desde o primeiro arquivo, então você pode abri-lo no editor do Macaly a qualquer momento e continuar a construção por lá.

O que você precisa

Você precisa de um cliente MCP que ofereça suporte a servidores remotos via Streamable HTTP: Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot ou Codex.

Conecte o seu cliente

O Claude, o ChatGPT, o Cursor e o Grok Bot instalam o Macaly Cloud a partir dos diretórios oficiais. No Macaly, em Configurações → Conexões, há um card para cada um deles, com os mesmos passos e um link para a página do diretório. Os outros clientes adicionam o servidor no endereço:

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

Nos dois casos, o seu cliente abre uma janela do navegador em que você faz login no Macaly e aprova o acesso (OAuth). Não há chaves para copiar.

Abra a página do Macaly Cloud no diretório de conectores do Claude. Ela funciona no claude.ai, no app para desktop e no celular.
Clique em Connect.
Faça login no Macaly e aprove o acesso na janela que se abrir.

Execute no seu terminal:

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

Depois, inicie o Claude Code e execute /mcp para fazer login no Macaly.

Abra o plugin do Macaly Cloud no Cursor Marketplace e adicione-o. Você também pode executar /add-plugin macaly-code no chat do Cursor.
Quando o Cursor abrir o navegador, faça login no Macaly e aprove o acesso.

Execute no seu terminal:

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

Como usar uma chave de API

Em vez do OAuth, você pode se autenticar com uma chave de API do Macaly. Isso é útil para agentes headless e automações. Envie a chave como bearer token:

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

As chaves de API são restritas a um único workspace, então as ferramentas que recebem um teamId o identificam automaticamente.

Crie um app do começo ao fim

Crie o app

O seu agente chama create_app com um nome. Ele recebe de volta um chatId e o briefing do projeto. O app é criado vazio, sem prompt inicial e sem build por IA.

Escreva o código

write_file grava um arquivo inteiro e edit_file substitui um trecho exato de um arquivo existente, então uma pequena alteração em um arquivo grande não precisa enviar o arquivo todo de novo. Cada chamada de write_file, edit_file e delete_file é um commit git atômico, com um registro próprio no histórico do app. A primeira escrita em um workspace inativo leva cerca de 20-30 segundos a mais enquanto o sandbox termina de iniciar.

Adicione recursos da plataforma

Para banco de dados, pagamentos, IA, mídia ou busca, o agente lê o guia com skill_info e executa os comandos dele com bash. O sandbox já tem as credenciais de que os guias precisam.

Verifique os tipos

Depois da última escrita, o agente executa bash ".sandbox/check-errors --strict", que captura erros de tipos, de estilo e de servidor em uma única passada, termina com um resumo do resultado e sai com erro quando o TypeScript ou o CSS falha. Se falhar, get_logs devolve a saída real.

Pré-visualização

A pré-visualização é reconstruída automaticamente alguns segundos depois da última escrita. Quando o build termina com sucesso, preview_app devolve a URL ativa para abrir ou compartilhar. Com path, o link abre direto uma subpágina, por exemplo /pricing. O agente chama preview_app no fim de toda rodada que alterou o app, mesmo quando um link anterior ainda é válido. Essa chamada avisa o Macaly que a rodada terminou.

Publique

Quando você pedir explicitamente para colocar o app no ar, o agente chama publish_app e consulta get_deployment com o deploymentId devolvido até o status ser READY. Depois, ele passa para você o liveUrl, o endereço da versão que está no ar. O connect_domain conecta um domínio personalizado ou renomeia o subdomínio do Macaly.

Ferramentas disponíveis

O Macaly Cloud expõe 20 ferramentas.

Workspaces e apps

Ferramenta	O que faz
`list_teams`	Lista os workspaces em que você pode construir
`create_app`	Cria um app novo e vazio na stack padrão e devolve o briefing dele
`list_projects`	Lista os apps de um workspace, dos atualizados mais recentemente aos mais antigos, com busca e paginação. Os apps fixados aparecem na primeira página
`get_project`	Resumo do estado: situação do build da pré-visualização, URL da pré-visualização, o status da publicação mais recente e o `liveUrl`, o briefing e quem está trabalhando no app no momento
`get_messages`	Lê o histórico do chat do app, com o que foi pedido e construído até agora, antes de fazer alterações
`duplicate_app`	Faz um fork de um app, com o histórico, em um app novo

Código

Ferramenta	O que faz
`list_files`	Lista os arquivos de código-fonte do app
`read_file`	Lê um arquivo pelo caminho, ou só um intervalo de linhas com `startLine` e `endLine`
`write_file`	Grava um arquivo inteiro e faz o commit imediatamente
`edit_file`	Substitui um trecho exato de um arquivo existente e faz o commit imediatamente: até 20 substituições por chamada, aplicadas todas ou nenhuma
`delete_file`	Exclui um arquivo e faz o commit da exclusão imediatamente
`bash`	Executa um comando de shell no sandbox do app: instalações, CLIs, scripts de habilidades e a verificação de tipos `.sandbox/check-errors --strict`. Um comando pode ter até 32.000 caracteres e rodar por até 240 segundos

Mídia

Ferramenta	O que faz
`upload_file`	Adiciona um arquivo à biblioteca de mídia do app e devolve a URL pública permanente dele (até 1 GB). O arquivo vem de uma URL acessível publicamente, ou do seu computador ou do sandbox do app por meio de um comando `curl` pronto
`list_media`	Lista os arquivos da biblioteca de mídia do app com as URLs públicas deles e devolve um link em que você pode soltar um arquivo local

Nenhuma ferramenta aceita bytes brutos de arquivo. Para um arquivo no seu computador, upload_file devolve um comando curl que o seu agente executa no seu próprio shell. Para um arquivo que o agente criou no sandbox, ele executa o comando no sandbox. Se o seu agente não tiver um shell, solte o arquivo na biblioteca de mídia pelo link do list_media.

Mantenha imagens, áudio e vídeo gerados ou baixados fora da pasta public/ do app. Cada build da pré-visualização envia public/ de novo, então muitos arquivos ou arquivos grandes deixam o build mais lento e podem fazê-lo falhar. Envie a mídia com upload_file e use a URL devolvida.

Recursos e diagnóstico

Ferramenta	O que faz
`skill_info`	Lê o guia de um recurso da plataforma, com comandos prontos para executar e os padrões de código a aplicar
`get_logs`	Busca os logs de build, do servidor de desenvolvimento ou da publicação
`preview_app`	Devolve um link de pré-visualização válido por três horas para compartilhar, opcionalmente para uma subpágina

Publicação

Ferramenta	O que faz
`publish_app`	Publica o app em produção na URL `macaly.app` dele
`get_deployment`	Consulta a tentativa de publicação mais recente (ou uma pelo `deploymentId`), o `liveUrl` e os domínios conectados
`connect_domain`	Conecta um domínio personalizado ou renomeia o subdomínio do app no Macaly

Cloud actions

Cloud actions são o que o seu agente externo faz por meio do Macaly Cloud. O plano Gratuito inclui 100 Cloud actions por mês. Os planos pagos não têm limite mensal de Cloud actions. Estas ações contam:

Criar ou duplicar um app (create_app, duplicate_app)
Escrever, editar ou excluir arquivos (write_file, edit_file, delete_file)
Executar comandos (bash)
Enviar arquivos (upload_file)
Publicar (publish_app)
Conectar um domínio (connect_domain)

Ler arquivos (read_file), listar e gerar prévias (preview_app) não custa nada. Conversar com o agente do próprio Macaly dentro do app não usa Cloud actions. A franquia do plano Gratuito é compartilhada por todo o workspace, é zerada no dia 1º de cada mês (UTC) e não acumula. Quando ela acaba, as demais ações contabilizadas são recusadas, com a data de renovação e um link para Cobrança. As leituras, os apps que já estão no ar e as conversas com o Macaly dentro do app continuam funcionando. Cobrança e Configurações → Uso e limites mostram quantas Cloud actions você já usou. Veja Uso e limites.

Como trabalhar junto com o editor do Macaly

Um app criado pelo Macaly Cloud é um app comum do Macaly. Você pode abri-lo no editor, ver o histórico de versões, restaurar uma versão anterior ou continuar com o agente do próprio Macaly.

Toda alteração fica registrada. Cada escrita traz uma breve explicação do seu agente, que aparece no histórico do chat do app como um card com o nome do cliente que a fez. Assim, o agente do Macaly tem o contexto caso você continue por lá depois. Quando uma execução com várias alterações termina, o card resume o que mudou.
Você pode voltar atrás. Clique em Restaurar a versão anterior em um card para deixar o app como estava depois daquela execução. Isso remove do chat tudo o que veio depois. Duplicar copia essa versão para um novo projeto.
Um card por rodada. O Macaly não vê as mensagens que você envia ao seu agente, só as chamadas de ferramentas dele. Uma execução termina quando o seu agente devolve o app com preview_app ou publish_app. Se ele pular essa chamada, vários pedidos seus podem acabar em um único card.
Só um agente por vez. Enquanto o seu agente externo trabalha, o chat fica bloqueado: o agente do Macaly não inicia uma rodada e o campo de mensagem mostra quem está com o app. O bloqueio é liberado sozinho alguns minutos depois da última escrita, ou assim que o seu agente mostrar a pré-visualização.
A pré-visualização espera o app ficar pronto. Os rebuilds feitos durante a construção ficam em espera, então o painel de pré-visualização continua mostrando o app que você já tinha até a execução terminar.

Exemplos de prompts

Crie para mim um app no Macaly: uma landing page para um serviço
de assinatura de café, com hero, preços e um formulário de
cadastro de e-mail.

Adicione um botão de modo escuro ao meu app de café no Macaly,
verifique os tipos e me passe o link da pré-visualização.

Configure um banco de dados para o meu app de café e guarde nele
os e-mails cadastrados.

Publique o app de café e conecte o domínio coffee.example.com.

Solução de problemas

Uma escrita retorna CHAT_CLAIMED_BY_AGENT ou CHAT_CLAIMED_BY_EDITOR

Outra pessoa está com o app: o agente do próprio Macaly está no meio de uma rodada, ou outro editor externo escreveu nele recentemente. Aguarde e tente de novo. O bloqueio é liberado sozinho alguns minutos depois da última atividade.

O build da pré-visualização falha por tempo limite no upload

A saída do build é grande demais ou tem arquivos demais, geralmente mídia em public/. get_logs com log_type: "build" mostra a quantidade e o tamanho dos arquivos. Tire a mídia de public/ com upload_file, use as URLs devolvidas e deixe a pré-visualização ser reconstruída.

A URL da pré-visualização ainda não mostra nada

As pré-visualizações são servidas a partir de um build concluído. Verifique previewBuildStatus com get_project e, se o build falhou, leia get_logs com log_type: "build".

Uma ação é recusada porque minhas Cloud actions acabaram

O plano Gratuito inclui 100 Cloud actions por mês. A mensagem de recusa mostra a data em que elas são renovadas (dia 1º do mês, UTC) e um link para Cobrança. As leituras e as prévias continuam funcionando. Faça upgrade para o Starter ou o Pro para remover o limite mensal.

Uma ferramenta retorna FORBIDDEN

Ou o workspace em que você está atuando tem o Macaly Cloud desativado, ou a ação exige um recurso de plano que você não tem, como publicar em um domínio personalizado.

Ainda com dúvidas? Fale conosco pelo chat no Macaly ou consulte as Perguntas frequentes.

​O que você precisa

​Conecte o seu cliente

​Como usar uma chave de API

​Crie um app do começo ao fim

​Ferramentas disponíveis

​Workspaces e apps

​Código

​Mídia

​Recursos e diagnóstico

​Publicação

​Cloud actions

​Como trabalhar junto com o editor do Macaly

​Exemplos de prompts

​Solução de problemas

O que você precisa

Conecte o seu cliente

Como usar uma chave de API

Crie um app do começo ao fim

Ferramentas disponíveis

Workspaces e apps

Código

Mídia

Recursos e diagnóstico

Publicação

Cloud actions

Como trabalhar junto com o editor do Macaly

Exemplos de prompts

Solução de problemas