Servidor MCP Macaly Cloud - Macaly Documentation

O Macaly Cloud é um servidor MCP que transforma o Macaly na infraestrutura por trás do teu próprio agente de programação com IA. O teu agente escreve cada linha de código; o Macaly fornece o repositório git, a sandbox na cloud, a base de dados e as capacidades da plataforma, a compilação, a pré-visualização partilhável e o alojamento em produção em macaly.app. Nada é gerado no teu computador e o agente do Macaly nunca é executado. A app vive no teu workspace do Macaly desde o primeiro ficheiro, por isso podes abri-la no editor do Macaly quando quiseres e continuar a construir aí.

O que precisas

Precisas de um cliente MCP compatível com servidores remotos por Streamable HTTP - Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot ou Codex.

Liga o teu cliente

O Claude, o ChatGPT, o Cursor e o Grok Bot instalam o Macaly Cloud a partir dos seus diretórios oficiais. No Macaly, em Definições → Ligações, há um cartão para cada um deles com os mesmos passos e uma ligação para a entrada no diretório. Os outros clientes adicionam o servidor em:

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

Em ambos os casos, o teu cliente abre uma janela do navegador onde inicias sessão no Macaly e aprovas o acesso (OAuth). Não há chaves para copiar.

Abre a página do Macaly Cloud no diretório de conectores do Claude. Funciona no claude.ai, na app de ambiente de trabalho e no telemóvel.
Clica em Connect.
Inicia sessão no Macaly e aprova o acesso na janela que abre.

Executa no terminal:

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

Depois inicia o Claude Code e executa /mcp para iniciares sessão no Macaly.

Abre o plugin do Macaly Cloud no Cursor Marketplace e adiciona-o. Também podes executar /add-plugin macaly-code no chat do Cursor.
Quando o Cursor abrir o navegador, inicia sessão no Macaly e aprova o acesso.

Executa no terminal:

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

Usar uma chave API

Podes autenticar-te com uma chave API do Macaly em vez de OAuth - útil para agentes headless e automação. Passa 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 API pertencem a um único workspace, por isso as ferramentas que aceitam teamId descobrem-no sozinhas.

Constrói uma app do início ao fim

Cria a app

O teu agente chama create_app com um nome. Recebe um chatId e o briefing do projeto. A app é criada vazia: sem prompt inicial e sem build de IA.

Escreve o código

O write_file escreve um ficheiro inteiro e o edit_file substitui texto exato num ficheiro existente, por isso uma pequena alteração num ficheiro grande não volta a enviar o ficheiro todo. Cada chamada a write_file, edit_file e delete_file é um commit git atómico com a sua própria entrada no histórico da app. A primeira escrita num workspace frio demora mais 20-30 segundos enquanto a sandbox arranca.

Acrescenta capacidades da plataforma

Para base de dados, pagamentos, IA, media ou pesquisa, o agente lê o guia com skill_info e executa os comandos com bash - a sandbox já tem as credenciais de que os guias precisam.

Verifica os tipos

Depois da última escrita, o agente executa bash ".sandbox/check-errors --strict" - apanha erros de tipos, de estilos e do servidor de uma só vez, termina com um resumo do resultado e sai com erro quando o TypeScript ou o CSS falham. Se falhar, o get_logs devolve a saída real.

Pré-visualiza

A pré-visualização é recompilada automaticamente poucos segundos depois da última escrita. Assim que a build passa, o preview_app devolve o URL em direto para abrires ou partilhares. Com path, o link abre diretamente uma subpágina, por exemplo /pricing. O agente chama preview_app no fim de cada turno que alterou a app, mesmo quando um link anterior ainda é válido - essa chamada indica ao Macaly que o turno terminou.

Publica

Quando pedires explicitamente para ir para o ar, o agente chama publish_app e consulta o get_deployment com o deploymentId devolvido até o estado ser READY. Depois dá-te o liveUrl, o endereço da versão que está no ar. O connect_domain liga um domínio próprio ou muda o nome do subdomínio Macaly.

Ferramentas disponíveis

O Macaly Cloud disponibiliza 20 ferramentas.

Workspaces e apps

Ferramenta	O que faz
`list_teams`	Lista os workspaces onde podes construir
`create_app`	Cria uma app nova e vazia na stack predefinida e devolve o respetivo briefing
`list_projects`	Lista as apps de um workspace, das mais recentes primeiro, com pesquisa e paginação. As apps fixadas aparecem na primeira página
`get_project`	Estado do projeto: build da pré-visualização, URL de pré-visualização, o estado da publicação mais recente e o `liveUrl`, o briefing e quem está a trabalhar na app
`get_messages`	Lê o histórico de chat da app - o que foi pedido e o que já foi construído - antes de fazer alterações
`duplicate_app`	Duplica uma app com o histórico para uma nova

Código

Ferramenta	O que faz
`list_files`	Lista os ficheiros de código da app
`read_file`	Lê um ficheiro pelo caminho, ou só um intervalo de linhas com `startLine` e `endLine`
`write_file`	Escreve um ficheiro por inteiro e faz commit imediatamente
`edit_file`	Substitui texto exato num ficheiro existente e faz commit imediatamente - até 20 substituições por chamada, aplicadas todas ou nenhuma
`delete_file`	Elimina um ficheiro e faz commit da eliminação imediatamente
`bash`	Executa um comando de shell na sandbox da app - instalações, CLIs, scripts de skills e a verificação `.sandbox/check-errors --strict`. Um comando pode ter até 32 000 caracteres e correr até 240 segundos

Média

Ferramenta	O que faz
`upload_file`	Adiciona um ficheiro à biblioteca de média da app e devolve o seu URL público permanente (até 1 GB). O ficheiro vem de um URL publicamente acessível, ou do teu computador ou da sandbox da app através de um comando `curl` pronto a usar
`list_media`	Lista os ficheiros da biblioteca de média da app com os respetivos URLs públicos e devolve um link onde podes largar um ficheiro local

Nenhuma ferramenta aceita bytes de ficheiro em bruto. Para um ficheiro no teu computador, o upload_file devolve um comando curl que o teu agente executa na tua própria shell. Para um ficheiro que o agente criou na sandbox, ele executa o comando na sandbox. Se o teu agente não tiver shell, larga o ficheiro na biblioteca de média com o link do list_media.

Mantém as imagens, o áudio e os vídeos gerados ou descarregados fora da pasta public/ da app. Cada build da pré-visualização volta a carregar public/, por isso muitos ficheiros ou ficheiros grandes tornam a build mais lenta e podem fazê-la falhar. Carrega a média com upload_file e usa o URL devolvido.

Capacidades e diagnóstico

Ferramenta	O que faz
`skill_info`	Lê o guia de uma capacidade da plataforma, com comandos prontos a correr e os padrões de código a aplicar
`get_logs`	Obtém registos de build, do servidor de desenvolvimento ou do deployment
`preview_app`	Devolve um link de pré-visualização válido durante três horas para partilhar, opcionalmente para uma subpágina

Publicação

Ferramenta	O que faz
`publish_app`	Publica a app em produção no seu URL `macaly.app`
`get_deployment`	Consulta a tentativa de publicação mais recente (ou uma pelo `deploymentId`), o `liveUrl` e os domínios ligados
`connect_domain`	Liga um domínio próprio ou muda o nome do subdomínio Macaly

Ações Cloud

As ações Cloud são o que o teu agente externo faz através do Macaly Cloud. O plano Grátis inclui 100 ações Cloud por mês. Os planos pagos não têm limite mensal de ações Cloud. Estas ações contam:

Criar ou duplicar uma app (create_app, duplicate_app)
Escrever, editar ou eliminar ficheiros (write_file, edit_file, delete_file)
Executar comandos (bash)
Carregar ficheiros (upload_file)
Publicar (publish_app)
Ligar um domínio (connect_domain)

Ler ficheiros (read_file), listar e as pré-visualizações (preview_app) são gratuitos. Conversar com o agente do próprio Macaly dentro da app não usa ações Cloud. O limite do plano Grátis é partilhado por todo o workspace, é reposto no dia 1 de cada mês (UTC) e não transita. Quando se esgota, as ações contabilizadas seguintes são recusadas, com a data de reposição e um link para a Faturação. As leituras, as apps que já estão online e a conversa com o Macaly dentro da app continuam a funcionar. A Faturação e Definições → Uso e limites mostram quantas ações Cloud já usaste. Vê Uso e limites.

Trabalhar em paralelo com o editor do Macaly

Uma app construída através do Macaly Cloud é uma app do Macaly como qualquer outra. Podes abri-la no editor, ver o histórico de versões, reverter ou continuar com o agente do Macaly.

Todas as alterações ficam registadas. Cada escrita traz uma breve explicação do teu agente, que aparece no histórico do chat como um cartão com o nome do cliente que a fez - assim o agente do Macaly tem o contexto se continuares por lá. Quando uma sessão com várias alterações termina, o cartão resume o que mudou.
Podes voltar atrás. Clica em Restaurar a versão anterior num cartão para repor a app como estava depois dessa sessão. Isto remove do chat tudo o que veio a seguir. Duplicar copia essa versão para um novo projeto.
Um cartão por turno. O Macaly não vê as mensagens que envias ao teu agente, só as chamadas às ferramentas. Uma sessão termina quando o teu agente devolve a app com preview_app ou publish_app. Se ele saltar essa chamada, vários pedidos teus podem acabar num só cartão.
Só um agente de cada vez. Enquanto o teu agente externo trabalha, o chat fica bloqueado: o agente do Macaly não inicia um turno e a caixa de mensagem indica quem tem a app. O bloqueio liberta-se sozinho poucos minutos depois da última escrita, ou assim que o teu agente te mostra a pré-visualização.
A pré-visualização espera pela app terminada. As recompilações a meio são retidas, por isso o painel continua a mostrar a app que já tinhas até a sessão terminar.

Exemplos de prompts

Constrói-me uma app no Macaly: uma landing page para um serviço de
subscrição de café com hero, preços e formulário de inscrição por e-mail.

Adiciona um botão de modo escuro à minha app do café no Macaly,
verifica os tipos e dá-me o link da pré-visualização.

Configura uma base de dados para a minha app do café e guarda lá
as inscrições por e-mail.

Publica a app do café e liga o domínio coffee.example.com.

Resolução de problemas

A janela de início de sessão não aparece

Confirma que o teu cliente suporta servidores MCP remotos com OAuth e que introduziste o URL completo, incluindo o caminho /api/cloud/mcp.

Uma escrita devolve CHAT_CLAIMED_BY_AGENT ou CHAT_CLAIMED_BY_EDITOR

A app está com outra pessoa: o agente do Macaly está a meio de um turno, ou outro editor externo escreveu há pouco. Espera e tenta de novo - o bloqueio liberta-se sozinho poucos minutos depois da última atividade.

A build da pré-visualização falha por tempo esgotado no carregamento

O resultado da build é demasiado grande ou tem ficheiros a mais, normalmente média em public/. O get_logs com log_type: "build" mostra o número e o tamanho dos ficheiros. Tira a média de public/ com upload_file, usa os URLs devolvidos e deixa a pré-visualização compilar de novo.

O URL de pré-visualização ainda não mostra nada

As pré-visualizações são servidas a partir de uma build concluída. Verifica o previewBuildStatus com get_project e, se falhou, lê o get_logs com log_type: "build".

Uma ação é recusada porque as minhas ações Cloud se esgotaram

O plano Grátis inclui 100 ações Cloud por mês. A mensagem de recusa mostra a data em que são repostas (dia 1 do mês, UTC) e um link para a Faturação. As leituras e as pré-visualizações continuam a funcionar. Muda para o Starter ou o Pro para remover o limite mensal.

Uma ferramenta devolve FORBIDDEN

Ou o workspace em que estás a atuar tem o Macaly Cloud desativado, ou a ação exige uma funcionalidade de plano que não tens - publicar num domínio próprio, por exemplo.

Continuas com dúvidas? Fala connosco pelo chat do Macaly ou consulta as FAQ.

​O que precisas

​Liga o teu cliente

​Usar uma chave API

​Constrói uma app do início ao fim

​Ferramentas disponíveis

​Workspaces e apps

​Código

​Média

​Capacidades e diagnóstico

​Publicação

​Ações Cloud

​Trabalhar em paralelo com o editor do Macaly

​Exemplos de prompts

​Resolução de problemas

O que precisas

Liga o teu cliente

Usar uma chave API

Constrói uma app do início ao fim

Ferramentas disponíveis

Workspaces e apps

Código

Média

Capacidades e diagnóstico

Publicação

Ações Cloud

Trabalhar em paralelo com o editor do Macaly

Exemplos de prompts

Resolução de problemas