Servidor MCP Macaly Cloud - Macaly Documentation

Macaly Cloud es un servidor MCP que convierte Macaly en la infraestructura de tu propio agente de programación con IA. Tu agente escribe cada línea de código; Macaly aporta el repositorio git, el sandbox en la nube, la base de datos y las capacidades de la plataforma, la compilación, la vista previa compartible y el alojamiento en producción en macaly.app. No se genera nada en tu ordenador y el agente de Macaly nunca se ejecuta. La aplicación vive en tu workspace de Macaly desde el primer archivo, así que puedes abrirla en el editor de Macaly cuando quieras y seguir construyendo allí.

Qué necesitas

Necesitas un cliente MCP compatible con servidores remotos por Streamable HTTP: Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot o Codex.

Conecta tu cliente

Claude, ChatGPT, Cursor y Grok Bot instalan Macaly Cloud desde sus directorios oficiales. En Macaly, Ajustes → Conexiones tiene una tarjeta para cada uno de ellos con los mismos pasos y un enlace a la ficha. Los demás clientes añaden el servidor en:

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

En ambos casos, tu cliente abre una ventana del navegador donde inicias sesión en Macaly y apruebas el acceso (OAuth). No hay claves que copiar.

Abre la ficha de Macaly Cloud en el directorio de conectores de Claude. Funciona en claude.ai, en la app de escritorio y en el móvil.
Haz clic en Connect.
Inicia sesión en Macaly y aprueba el acceso en la ventana que se abre.

Ejecuta en tu terminal:

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

Después inicia Claude Code y ejecuta /mcp para iniciar sesión en Macaly.

Abre el plugin de Macaly Cloud en el Cursor Marketplace y añádelo. También puedes ejecutar /add-plugin macaly-code en el chat de Cursor.
Cuando Cursor abra el navegador, inicia sesión en Macaly y aprueba el acceso.

Ejecuta en tu terminal:

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

Usar una clave API en su lugar

Puedes autenticarte con una clave API de Macaly en lugar de OAuth, algo útil para agentes headless y automatizaciones. Pasa la clave como bearer token:

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

Las claves API pertenecen a un único workspace, así que las herramientas que aceptan teamId lo deducen automáticamente.

Construye una aplicación de principio a fin

Crea la aplicación

Tu agente llama a create_app con un nombre. Recibe un chatId y el briefing del proyecto. La aplicación se crea vacía: sin prompt inicial y sin build de IA.

Escribe el código

write_file escribe un archivo completo y edit_file reemplaza texto exacto en un archivo existente, así que un cambio pequeño en un archivo grande no vuelve a enviar todo el archivo. Cada llamada a write_file, edit_file y delete_file es un commit de git atómico con su propia entrada en el historial de la aplicación. La primera escritura en un workspace frío tarda unos 20-30 segundos más mientras arranca el sandbox.

Añade capacidades de la plataforma

Para base de datos, pagos, IA, medios o búsqueda, el agente lee la guía con skill_info y ejecuta sus comandos con bash: el sandbox ya tiene las credenciales que necesitan las guías.

Comprueba los tipos

Tras la última escritura, el agente ejecuta bash ".sandbox/check-errors --strict": detecta errores de tipos, de estilos y del servidor en una sola pasada, termina con un resumen del resultado y sale con un error cuando falla TypeScript o CSS. Si falla, get_logs devuelve la salida real.

Vista previa

La vista previa se recompila automáticamente unos segundos después de la última escritura. Cuando termina bien, preview_app devuelve la URL en vivo para abrir o compartir. Con path, el enlace abre directamente una subpágina, por ejemplo /pricing. El agente llama a preview_app al final de cada turno en el que cambió la aplicación, también cuando un enlace anterior sigue siendo válido: esa llamada le indica a Macaly que el turno ha terminado.

Publica

Cuando pidas explícitamente salir a producción, el agente llama a publish_app y consulta get_deployment con el deploymentId devuelto hasta que el estado sea READY. Después te da liveUrl, la dirección de la versión que está en vivo. connect_domain conecta un dominio propio o renombra el subdominio de Macaly.

Herramientas disponibles

Macaly Cloud expone 20 herramientas.

Workspaces y aplicaciones

Herramienta	Qué hace
`list_teams`	Lista los workspaces en los que puedes construir
`create_app`	Crea una aplicación nueva y vacía con el stack por defecto y devuelve su briefing
`list_projects`	Lista las aplicaciones de un workspace, las más recientes primero, con búsqueda y paginación. Las aplicaciones fijadas aparecen en la primera página
`get_project`	Estado actual: build de la vista previa, URL de vista previa, el estado de la publicación más reciente y `liveUrl`, el briefing y quién está trabajando en la aplicación
`get_messages`	Lee el historial de chat de la aplicación - qué se pidió y qué se ha construido - antes de hacer cambios
`duplicate_app`	Duplica una aplicación con su historial en una nueva

Código

Herramienta	Qué hace
`list_files`	Lista los archivos fuente de la aplicación
`read_file`	Lee un archivo por su ruta, o solo un rango de líneas con `startLine` y `endLine`
`write_file`	Escribe un archivo completo y lo commitea de inmediato
`edit_file`	Reemplaza texto exacto en un archivo existente y lo commitea de inmediato: hasta 20 reemplazos por llamada, se aplican todos o ninguno
`delete_file`	Elimina un archivo y commitea el borrado de inmediato
`bash`	Ejecuta un comando de shell en el sandbox de la aplicación: instalaciones, CLIs, scripts de skills y la comprobación `.sandbox/check-errors --strict`. Un comando puede tener hasta 32.000 caracteres y ejecutarse durante un máximo de 240 segundos

Medios

Herramienta	Qué hace
`upload_file`	Añade un archivo a la biblioteca de medios de la aplicación y devuelve su URL pública permanente (hasta 1 GB). El archivo viene de una URL pública, o de tu ordenador o del sandbox de la aplicación mediante un comando `curl` ya preparado
`list_media`	Lista los archivos de la biblioteca de medios de la aplicación con sus URLs públicas y devuelve un enlace donde puedes soltar un archivo local

Ninguna herramienta acepta bytes de archivo en bruto. Para un archivo de tu ordenador, upload_file devuelve un comando curl que tu agente ejecuta en tu propia shell. Para un archivo que el agente creó en el sandbox, ejecuta el comando en el sandbox. Si tu agente no tiene shell, suelta el archivo en la biblioteca de medios con el enlace de list_media.

No guardes imágenes, audio ni vídeo generados o descargados en la carpeta public/ de la aplicación. Cada build de la vista previa vuelve a subir public/, así que muchos archivos o archivos grandes ralentizan el build y pueden hacer que falle. Sube los medios con upload_file y usa la URL devuelta.

Capacidades y diagnóstico

Herramienta	Qué hace
`skill_info`	Lee la guía de una capacidad de la plataforma, con comandos listos para ejecutar y los patrones de código a aplicar
`get_logs`	Obtiene registros de build, del servidor de desarrollo o del despliegue
`preview_app`	Devuelve un enlace de vista previa válido durante tres horas para compartir, opcionalmente de una subpágina

Publicación

Herramienta	Qué hace
`publish_app`	Publica la aplicación en producción en su URL `macaly.app`
`get_deployment`	Consulta el intento de publicación más reciente (o uno concreto por `deploymentId`), `liveUrl` y los dominios conectados
`connect_domain`	Conecta un dominio propio o renombra el subdominio de Macaly

Acciones de Cloud

Las acciones de Cloud son lo que hace tu agente externo a través de Macaly Cloud. El plan Gratis incluye 100 acciones de Cloud al mes. Los planes de pago no tienen límite mensual de acciones de Cloud. Estas acciones cuentan:

Crear o duplicar una aplicación (create_app, duplicate_app)
Escribir, editar o eliminar archivos (write_file, edit_file, delete_file)
Ejecutar comandos (bash)
Subir archivos (upload_file)
Publicar (publish_app)
Conectar un dominio (connect_domain)

Leer archivos (read_file), listar y las vistas previas (preview_app) son gratuitas. Chatear con el propio agente de Macaly dentro de la aplicación no consume acciones de Cloud. La asignación del plan Gratis es compartida por todo el espacio de trabajo, se restablece el día 1 de cada mes (UTC) y no se acumula. Cuando se agota, las siguientes acciones que cuentan se rechazan indicando la fecha de restablecimiento y con un enlace a Facturación. Las lecturas, las aplicaciones que ya están en línea y el chat con Macaly dentro de la aplicación siguen funcionando. Facturación y Ajustes → Uso y límites muestran cuántas acciones de Cloud has usado. Consulta Uso y límites.

Trabajar junto al editor de Macaly

Una aplicación construida con Macaly Cloud es una aplicación de Macaly como cualquier otra. Puedes abrirla en el editor, revisar el historial de versiones, revertir o seguir con el propio agente de Macaly.

Todo cambio queda registrado. Cada escritura lleva una breve explicación de tu agente, que aparece en el historial del chat como una tarjeta con el nombre del cliente que la hizo, de modo que el agente de Macaly tenga el contexto si continúas allí. Cuando termina una sesión con varios cambios, su tarjeta resume lo que ha cambiado.
Puedes volver atrás. Haz clic en Restaurar la versión anterior en una tarjeta para devolver la aplicación al estado en que quedó tras esa sesión. Esto elimina del chat todo lo que vino después. Duplicar copia esa versión en un proyecto nuevo.
Una tarjeta por turno. Macaly no ve tus mensajes a tu agente, solo sus llamadas a herramientas. Una sesión termina cuando tu agente te entrega la aplicación con preview_app o publish_app. Si omite esa llamada, varias de tus peticiones pueden acabar en una sola tarjeta.
Un solo agente a la vez. Mientras trabaja tu agente externo, el chat queda bloqueado: el agente de Macaly no iniciará un turno y el campo de mensaje te indica quién tiene la aplicación. El bloqueo se libera solo unos minutos después de la última escritura, o en cuanto tu agente te muestra la vista previa.
La vista previa espera a la aplicación terminada. Las recompilaciones intermedias se retienen, así que el panel sigue mostrando la aplicación que ya tenías hasta que la sesión acaba.

Ejemplos de prompts

Créame una aplicación en Macaly: una landing page para un servicio
de suscripción de café con hero, precios y formulario de suscripción.

Añade un interruptor de modo oscuro a mi aplicación de café en Macaly,
comprueba los tipos y dame el enlace de vista previa.

Configura una base de datos para mi aplicación de café y guarda ahí
las suscripciones por correo.

Publica la aplicación de café y conecta el dominio coffee.example.com.

Solución de problemas

No aparece la ventana de inicio de sesión

Comprueba que tu cliente admite servidores MCP remotos con OAuth y que has introducido la URL completa, incluida la ruta /api/cloud/mcp.

Una escritura devuelve CHAT_CLAIMED_BY_AGENT o CHAT_CLAIMED_BY_EDITOR

La aplicación la tiene otro: el agente de Macaly está a mitad de un turno, o otro editor externo ha escrito hace poco. Espera y reinténtalo: el bloqueo se libera solo unos minutos después de la última actividad.

El build de la vista previa falla por tiempo de espera agotado en la subida

La salida del build es demasiado grande o tiene demasiados archivos, normalmente medios en public/. get_logs con log_type: "build" muestra el número de archivos y su tamaño. Saca los medios de public/ con upload_file, usa las URLs devueltas y deja que la vista previa se vuelva a compilar.

La URL de vista previa aún no muestra nada

Las vistas previas se sirven desde un build completado. Consulta previewBuildStatus con get_project y, si ha fallado, lee get_logs con log_type: "build".

Una acción se rechaza porque se han agotado mis acciones de Cloud

El plan Gratis incluye 100 acciones de Cloud al mes. El mensaje de rechazo indica la fecha en que se restablecen (el día 1 del mes, UTC) y un enlace a Facturación. Las lecturas y las vistas previas siguen funcionando. Cambia a Starter o Pro para quitar el límite mensual.

Una herramienta devuelve FORBIDDEN

O el workspace en el que actúas tiene Macaly Cloud desactivado, o la acción requiere una función de plan que no tienes, como publicar en un dominio propio.

¿Sigues atascado? Escríbenos por el chat de Macaly o consulta las preguntas frecuentes.

​Qué necesitas

​Conecta tu cliente

​Usar una clave API en su lugar

​Construye una aplicación de principio a fin

​Herramientas disponibles

​Workspaces y aplicaciones

​Código

​Medios

​Capacidades y diagnóstico

​Publicación

​Acciones de Cloud

​Trabajar junto al editor de Macaly

​Ejemplos de prompts

​Solución de problemas

Qué necesitas

Conecta tu cliente

Usar una clave API en su lugar

Construye una aplicación de principio a fin

Herramientas disponibles

Workspaces y aplicaciones

Código

Medios

Capacidades y diagnóstico

Publicación

Acciones de Cloud

Trabajar junto al editor de Macaly

Ejemplos de prompts

Solución de problemas