> ## 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.
# Servidor MCP do Macaly Cloud
> Deixe o Claude, o ChatGPT, o Cursor, o Grok Bot ou o Codex escrever o código, e o Macaly executa, faz o build e hospeda
O Macaly Cloud é um servidor [MCP](https://modelcontextprotocol.io) 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.
1. Abra a [página do Macaly Cloud](https://claude.ai/directory/macaly-cloud) no diretório de conectores do Claude. Ela funciona no claude.ai, no app para desktop e no celular.
2. Clique em **Connect**.
3. Faça login no Macaly e aprove o acesso na janela que se abrir.
Execute no seu terminal:
```bash theme={null}
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.
1. Abra o [plugin do Macaly Cloud](https://chatgpt.com/plugins/plugin_asdk_app_6a732e22122c8191ac404137c0514300) no diretório de plugins do ChatGPT. O mesmo plugin funciona no navegador e no app para desktop.
2. Clique em **Install**.
3. Quando o ChatGPT pedir para conectar a sua conta, faça login no Macaly e aprove o acesso na janela que se abrir.
1. Abra o [plugin do Macaly Cloud](https://cursor.com/marketplace/macaly) no Cursor Marketplace e adicione-o. Você também pode executar `/add-plugin macaly-code` no chat do Cursor.
2. Quando o Cursor abrir o navegador, faça login no Macaly e aprove o acesso.
1. No Grok Bot, selecione **Plugins** na barra lateral. No app para celular, toque no seu avatar e selecione **Plugins**.
2. Procure por **Macaly Cloud** e adicione-o.
3. Quando o Grok Bot pedir para você clicar em **Authorize**, faça login no Macaly e aprove o acesso no navegador.
4. Confirme que o plugin aparece em **Installed**. Depois disso, ele fica disponível para todos os Bots que você executar.
Execute no seu terminal:
```bash theme={null}
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](/docs/pt-BR/api/authentication). Isso é útil para agentes headless e automações. Envie a chave como bearer token:
```json theme={null}
{
"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
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.
`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.
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.
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.
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.
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](/docs/pt-BR/account/workspaces/usage).
## 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
Confira se o seu cliente oferece suporte a servidores MCP remotos com OAuth e se você informou a URL completa, incluindo o caminho `/api/cloud/mcp`.
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.
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.
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"`.
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.
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](/docs/pt-BR/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.