Macaly Cloud MCP Server
Let Claude, ChatGPT, Cursor, Grok Bot, or Codex write the code - Macaly runs, builds, and hosts it
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/mcpEither 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.
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
1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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 |
Cloud actions
Cloud actions are what your external agent does through Macaly Cloud. The Free plan includes 100 Cloud actions per month. Paid plans have no monthly Cloud action limit.
These actions count:
- Creating or duplicating an app (
create_app,duplicate_app) - Writing, editing, or deleting files (
write_file,edit_file,delete_file) - Running commands (
bash) - Uploading files (
upload_file) - Publishing (
publish_app) - Connecting a domain (
connect_domain)
Reading files (read_file), listing, and previews (preview_app) are free. Chatting with Macaly’s own agent inside the app does not use Cloud actions.
The Free allowance is shared by the whole workspace, resets on the 1st of each month (UTC), and does not roll over. When it is used up, further counted actions are refused with the reset date and a link to Billing. Reads, apps that are already live, and chatting with Macaly inside the app keep working. Billing and Settings → Usage & limits show how many Cloud actions you have used. See Usage & limits.
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_apporpublish_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
The sign-in window doesn't appear
Make sure your client supports remote MCP servers with OAuth, and that you entered the full URL including the /api/cloud/mcp path.
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.
An action is refused because my Cloud actions are used up
The Free plan includes 100 Cloud actions per month. The refusal message shows the date they reset (the 1st of the month, UTC) and a link to Billing. Reads and previews still work. Upgrade to a paid plan to remove the monthly limit.
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.