> ## 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 Macaly Cloud
> Deixa o Claude, o ChatGPT, o Cursor, o Grok Bot ou o Codex escreverem o código - o Macaly executa, compila e aloja
O Macaly Cloud é um servidor [MCP](https://modelcontextprotocol.io) 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.
1. Abre a [página do Macaly Cloud](https://claude.ai/directory/macaly-cloud) no diretório de conectores do Claude. Funciona no claude.ai, na app de ambiente de trabalho e no telemóvel.
2. Clica em **Connect**.
3. Inicia sessão no Macaly e aprova o acesso na janela que abre.
Executa no terminal:
```bash theme={null}
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.
1. Abre 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 na app de ambiente de trabalho.
2. Clica em **Install**.
3. Quando o ChatGPT pedir para ligar a tua conta, inicia sessão no Macaly e aprova o acesso na janela que abre.
1. Abre o [plugin do Macaly Cloud](https://cursor.com/marketplace/macaly) no Cursor Marketplace e adiciona-o. Também podes executar `/add-plugin macaly-code` no chat do Cursor.
2. Quando o Cursor abrir o navegador, inicia sessão no Macaly e aprova o acesso.
1. No Grok Bot, seleciona **Plugins** na barra lateral. Na app móvel, toca no teu avatar e seleciona **Plugins**.
2. Procura **Macaly Cloud** e adiciona-o.
3. Quando o Grok Bot pedir **Authorize**, inicia sessão no Macaly e aprova o acesso no navegador.
4. Confirma que o plugin aparece em **Installed**. A partir daí fica disponível para todos os Bots que executares.
Executa no terminal:
```bash theme={null}
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](/docs/pt/api/authentication) em vez de OAuth - útil para agentes headless e automação. Passa 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 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
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.
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.
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.
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.
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.
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](/docs/pt/account/workspaces/usage).
## 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
Confirma que o teu cliente suporta servidores MCP remotos com OAuth e que introduziste o URL completo, incluindo o caminho `/api/cloud/mcp`.
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.
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.
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"`.
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.
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](/docs/pt/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.