Macaly Cloud MCP Server - Macaly Documentation

Macaly Cloud is an MCP server that turns Macaly into the infrastructure behind your own AI coding agent. Your agent writes every line of code; Macaly supplies the git repository, the cloud sandbox, the database and platform capabilities, the build, the shareable preview, and production hosting on macaly.app. Nothing is generated on your computer, and Macaly’s own agent never runs. The app lives in your Macaly workspace from the first file, so you can open it in the Macaly editor at any time and keep building there.

What you need

You need an MCP client that supports remote servers over Streamable HTTP - Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot, or Codex.

Connect your client

Claude, ChatGPT, Cursor, and Grok Bot install Macaly Cloud from their official directories. In Macaly, Settings → Connections has a card for each of them with the same steps and a link to the listing. Other clients add the server at:

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

Either way, your client opens a browser window where you sign in to Macaly and approve access (OAuth). There are no keys to copy.

Open the Macaly Cloud listing in the Claude connectors directory. It works in claude.ai, the desktop app, and on mobile.
Click Connect.
Sign in to Macaly and approve access in the window that opens.

Run in your terminal:

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

Then start Claude Code and run /mcp to sign in to Macaly.

Open the Macaly Cloud plugin in the Cursor Marketplace and add it. You can also run /add-plugin macaly-code in the Cursor chat.
When Cursor opens your browser, sign in to Macaly and approve access.

Run in your terminal:

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

Using an API key instead

You can authenticate with a Macaly API key instead of OAuth - useful for headless agents and automation. Pass the key as a bearer token:

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

API keys are scoped to a single workspace, so tools that take a teamId figure it out automatically.

Build an app end to end

Create the app

Your agent calls create_app with a name. It gets back a chatId and the project briefing. The app is created empty - no starter prompt, no AI build.

Write the code

write_file writes a whole file, and edit_file replaces exact text in an existing file, so a small change to a large file does not send the whole file again. Each write_file, edit_file and delete_file call is one atomic git commit with its own entry in the app’s history. The first write on a cold workspace takes ~20-30 seconds longer while the sandbox finishes booting.

Add platform capabilities

For a database, payments, AI, media, or search, the agent reads the guide with skill_info and runs its commands with bash - the sandbox already holds the credentials the guides need.

Typecheck

After the last write, the agent runs bash ".sandbox/check-errors --strict" - it catches type, style, and server errors in one pass, ends with a result summary, and exits with an error when TypeScript or CSS fails. On failure, get_logs returns the real output.

Preview

The preview rebuilds automatically a few seconds after the last write. Once it succeeds, preview_app returns the live URL to open or share. With path, the link opens a subpage directly, for example /pricing. The agent calls preview_app at the end of every turn that changed the app, also when an earlier link is still valid - that call tells Macaly that the turn is finished.

Publish

When you explicitly ask to go live, the agent calls publish_app and polls get_deployment with the returned deploymentId until the status is READY. Then it gives you liveUrl, the address of the version that is live. connect_domain attaches a custom domain or renames the Macaly subdomain.

Available tools

Macaly Cloud exposes 20 tools.

Workspaces & apps

Tool	What it does
`list_teams`	List the workspaces you can build in
`create_app`	Create a new, empty app on the default stack and return its briefing
`list_projects`	List a workspace’s apps, most recently updated first, with search and pagination. Pinned apps come back on the first page
`get_project`	Status snapshot: preview build state, preview URL, the newest publish status and `liveUrl`, the briefing, and who is currently working on the app
`get_messages`	Read the app’s chat history — what was asked for and built so far — before making changes
`duplicate_app`	Fork an app with its history into a fresh one

Code

Tool	What it does
`list_files`	List the app’s source files
`read_file`	Read one file by path, or only a range of lines with `startLine` and `endLine`
`write_file`	Write one file in full and commit it immediately
`edit_file`	Replace exact text in an existing file and commit it immediately - up to 20 replacements per call, all applied or none
`delete_file`	Delete one file and commit the deletion immediately
`bash`	Run a shell command in the app’s sandbox - installs, CLIs, skill scripts, and the `.sandbox/check-errors --strict` typecheck. A command can have up to 32,000 characters and run for up to 240 seconds

Media

Tool	What it does
`upload_file`	Add a file to the app’s media library and get back its permanent public URL (up to 1 GB). The file comes from a publicly reachable URL, or from your computer or the app’s sandbox through a ready-made `curl` command
`list_media`	List the files in the app’s media library with their public URLs, and get a link where you can drop a local file in

No tool accepts raw file bytes. For a file on your computer, upload_file returns a curl command that your agent runs in your own shell. For a file that the agent made in the sandbox, it runs the command in the sandbox. If your agent has no shell, drop the file into the media library with the link from list_media.

Keep generated or downloaded images, audio, and video out of the app’s public/ folder. Every preview build uploads public/ again, so many or large files slow the build and can make it fail. Upload media with upload_file and use the returned URL.

Capabilities & diagnostics

Tool	What it does
`skill_info`	Read a platform capability’s guide, with ready-to-run commands and the code patterns to apply
`get_logs`	Fetch build, dev server, or deployment logs
`preview_app`	Return a three-hour preview link to share, optionally for a subpage

Publishing

Tool	What it does
`publish_app`	Publish the app to production at its `macaly.app` URL
`get_deployment`	Check the newest publish attempt (or one by `deploymentId`), `liveUrl`, and connected domains
`connect_domain`	Connect a custom domain, or rename the app’s Macaly subdomain

Working alongside the Macaly editor

An app built through Macaly Cloud is an ordinary Macaly app. You can open it in the editor, look at the version history, roll back, or continue with Macaly’s own agent.

Every change is recorded. Each write carries a short explanation from your agent, which appears in the app’s chat history as a card naming the client that made it - so Macaly’s agent has the context if you continue there later. When a run with several changes finishes, its card sums up what changed.
You can go back. Click Restore previous version on a card to return the app to how it was after that run. This removes everything after it from the chat. Duplicate copies that version into a new project.
One card for each turn. Macaly does not see your messages to your agent, only its tool calls. A run ends when your agent hands back the app with preview_app or publish_app. If it skips that call, several of your requests can end up in one card.
Only one agent at a time. While your external agent is working, the chat is locked: Macaly’s agent won’t start a turn, and the composer tells you who has the app. The lock clears itself a few minutes after the last write, or as soon as your agent shows you the preview.
The preview waits for the finished app. Mid-build rebuilds are held back, so the preview panel keeps showing the app you already had until the run ends.

Example prompts

Build me a Macaly app: a landing page for a coffee subscription
service with a hero, pricing, and an email signup form.

Add a dark mode toggle to my coffee app on Macaly, typecheck it,
and give me the preview link.

Set up a database for my coffee app and store the email signups in it.

Publish the coffee app and connect the domain coffee.example.com.

Troubleshooting

A write returns CHAT_CLAIMED_BY_AGENT or CHAT_CLAIMED_BY_EDITOR

Someone else has the app: Macaly’s own agent is mid-turn, or another external editor wrote to it recently. Wait and retry - the lock frees itself a few minutes after the last activity.

The preview build fails with an upload timeout

The build output is too large or has too many files, usually media in public/. get_logs with log_type: "build" shows the file count and size. Move the media out of public/ with upload_file, use the returned URLs, and let the preview build again.

The preview URL shows nothing yet

Previews serve from a completed build. Check previewBuildStatus with get_project, and read get_logs with log_type: "build" if it failed.

A tool returns FORBIDDEN

Either the workspace you’re acting on has Macaly Cloud disabled, or the action needs a plan feature you don’t have - publishing to a custom domain, for example.

Still stuck? Reach out via the chat in Macaly or check the FAQ.

​What you need

​Connect your client

​Using an API key instead

​Build an app end to end

​Available tools

​Workspaces & apps

​Code

​Media

​Capabilities & diagnostics

​Publishing

​Working alongside the Macaly editor

​Example prompts

​Troubleshooting

What you need

Connect your client

Using an API key instead

Build an app end to end

Available tools

Workspaces & apps

Code

Media

Capabilities & diagnostics

Publishing

Working alongside the Macaly editor

Example prompts

Troubleshooting