Macaly Cloud MCP Server

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, or Codex.

Connect your client

The server is available at:

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

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

Claude
Claude Code
ChatGPT
Codex

In claude.ai or the Claude desktop app, open Settings → Connectors.
Click Add custom connector.
Enter https://www.macaly.com/api/cloud/mcp and click Add.
Click Connect and approve access in the Macaly 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 Settings → Plugins. If you don’t see it, turn on Developer mode in Settings → Security and login first.
Click Add and choose Add MCP server.
Enter https://www.macaly.com/api/cloud/mcp and confirm.
Approve access in the Macaly window that opens.

Run in your terminal:

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

Connected via OAuth, your agent can act on any workspace you’re a member of. If you belong to more than one, ask it to “list my Macaly teams” first - create_app needs to know where to build.

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 16 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
`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

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.

Connections

Integrations

What you need

Connect your client

Using an API key instead

Build an app end to end

Available tools

Workspaces & apps

Code

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

​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

Capabilities & diagnostics

Publishing

Working alongside the Macaly editor

Example prompts

Troubleshooting