> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Macaly Cloud MCP Server
> Let Claude, ChatGPT, or Codex write the code - Macaly runs, builds, and hosts it
Macaly Cloud is an [MCP](https://modelcontextprotocol.io) 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.
1. In [claude.ai](https://claude.ai) or the Claude desktop app, open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter `https://www.macaly.com/api/cloud/mcp` and click **Add**.
4. Click **Connect** and approve access in the Macaly window that opens.
Run in your terminal:
```bash theme={null}
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.
1. Open **Settings → Plugins**. If you don't see it, turn on **Developer mode** in **Settings → Security and login** first.
2. Click **Add** and choose **Add MCP server**.
3. Enter `https://www.macaly.com/api/cloud/mcp` and confirm.
4. Approve access in the Macaly window that opens.
Run in your terminal:
```bash theme={null}
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](/docs/en/api/authentication) instead of OAuth - useful for headless agents and automation. Pass the key as a bearer token:
```json theme={null}
{
"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
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.
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.
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.
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.
The preview rebuilds automatically a few seconds after the last write. Once it succeeds, `preview_app` returns the live URL to open or share.
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
Make sure your client supports remote MCP servers with OAuth, and that you entered the full URL including the `/api/cloud/mcp` path.
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.
Previews serve from a completed build. Check `previewBuildStatus` with `get_project`, and read `get_logs` with `log_type: "build"` if it failed.
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](/docs/en/welcome/faq).