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 Claude and for ChatGPT 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

Each write_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" - it catches type, style, and server errors in one pass. 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.

Publish

When you explicitly ask to go live, the agent calls publish_app and polls get_deployment until the status is READY. connect_domain attaches a custom domain or renames the Macaly subdomain.

Available tools

Macaly Cloud exposes 18 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
`get_project`	Status snapshot: preview build state, preview and live URLs, 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
`write_file`	Write one file in full and commit it immediately
`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` typecheck

Media

Tool	What it does
`upload_file`	Import a file from a publicly reachable URL into the app’s media library and get back its permanent public URL (up to 1 GB)

No tool accepts raw file bytes. For a file that exists only on your computer, add it to the app’s media library in Macaly first, then give your agent the public URL it gets there.

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 the app’s live preview URL to share

Publishing

Tool	What it does
`publish_app`	Publish the app to production at its `macaly.app` URL
`get_deployment`	Check deployment status, the live URL, 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.
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 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