> ## 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 MCP Server

> Control Macaly from Claude, Cursor, ChatGPT, and other AI agents

The Macaly MCP server lets AI agents manage your Macaly apps programmatically using the [Model Context Protocol](https://modelcontextprotocol.io) — an open standard for connecting AI assistants to external tools. Connect it once, and your agent can create apps, request changes, review the generated code, and publish to production, all from a conversation.

This is the reverse of Macaly's other integrations: instead of the Macaly agent reaching out to your tools, an external agent (Claude, Cursor, ChatGPT, …) reaches into Macaly.

<Callout icon="user">
  Available on the Pro plan. Every workspace you act on through the MCP server must be on a Pro plan — see [Plan features and limits](#plan-features-and-limits).
</Callout>

## Why connect the MCP server

* **Build apps from your favorite AI client.** Describe an app in Claude or Cursor and the agent creates it in Macaly, waits for the build, and hands you the preview link.
* **Iterate without switching tools.** Request changes, follow the build status, and review what changed — straight from the chat you're already in.
* **Inspect the generated code.** List files, read sources, diff any edit, and revert to an earlier version if something went wrong.
* **Ship when you say so.** Publishing is a separate, explicit step. Your agent can take an app live and connect a custom domain — but only when you ask.

## What you need

* A **Macaly workspace on the Pro plan** — the MCP server is a Pro feature
* An MCP client that supports remote servers over Streamable HTTP, such as Claude (claude.ai and Desktop), Claude Code, Cursor, ChatGPT, or VS Code

## Connect your client

The server is available at:

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

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

<Tabs>
  <Tab title="Claude">
    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/mcp/mcp` and click **Add**.
    4. Click **Connect** and approve access in the Macaly window that opens.
  </Tab>

  <Tab title="Claude Code">
    Run in your terminal:

    ```bash theme={null}
    claude mcp add --transport http macaly https://www.macaly.com/api/mcp/mcp
    ```

    Then start Claude Code and run `/mcp` to sign in to Macaly.
  </Tab>

  <Tab title="Cursor">
    Add the server to `.cursor/mcp.json` (per project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "macaly": {
          "url": "https://www.macaly.com/api/mcp/mcp"
        }
      }
    }
    ```

    Cursor prompts you to sign in to Macaly the first time a tool is used.
  </Tab>

  <Tab title="ChatGPT">
    1. Open **Settings → Connectors** (requires developer mode or a plan with custom connectors).
    2. Click **Create** and enter `https://www.macaly.com/api/mcp/mcp`.
    3. Approve access in the Macaly window that opens.
  </Tab>

  <Tab title="VS Code">
    Add the server to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "macaly": {
          "type": "http",
          "url": "https://www.macaly.com/api/mcp/mcp"
        }
      }
    }
    ```

    VS Code walks you through the sign-in when the server first starts.
  </Tab>
</Tabs>

<Tip>
  Connected via OAuth, you can act on any workspace you're a member of. Ask your agent to "list my Macaly teams" first — most tools take a `teamId` so the agent knows where to work.
</Tip>

### Using an API key instead

On **Enterprise plans**, you can authenticate with a [Macaly API key](/en/api/authentication) instead of OAuth — useful for headless agents and automation. Pass the key as a bearer token:

```json theme={null}
{
  "mcpServers": {
    "macaly": {
      "url": "https://www.macaly.com/api/mcp/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.

## Available tools

### Workspaces & credits

| Tool         | What it does                                                               |
| ------------ | -------------------------------------------------------------------------- |
| `list_teams` | List the workspaces you can act on, with your role and credit balance      |
| `get_usage`  | Get a workspace's credit balance, plan, and approximate messages remaining |

### Apps

| Tool            | What it does                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------------- |
| `create_app`    | Create a new app from a prompt (optionally with image/file attachments) and start the first build |
| `list_projects` | List a workspace's apps, with search and pagination                                               |
| `get_project`   | Get one app's metadata: title, framework, deployment state, screenshot                            |
| `rename_app`    | Change an app's title                                                                             |
| `duplicate_app` | Fork an app (with its history) into a fresh app you can iterate on independently                  |
| `delete_app`    | Move an app to trash (published apps must be unpublished first)                                   |

### Building & iteration

| Tool               | What it does                                                                     |
| ------------------ | -------------------------------------------------------------------------------- |
| `send_message`     | Request a change to an existing app, like a follow-up message in the Macaly chat |
| `get_messages`     | Read an app's conversation history                                               |
| `get_build_status` | Poll the current build's status                                                  |
| `wait_for_build`   | Wait (server-side) until the build finishes or a timeout elapses                 |

### Code inspection

| Tool             | What it does                                                       |
| ---------------- | ------------------------------------------------------------------ |
| `list_files`     | List the app's generated source files                              |
| `read_file`      | Read one source file by path                                       |
| `list_edits`     | List the app's edit history — every AI turn that produced a commit |
| `get_diff`       | Get the unified diff for an edit                                   |
| `revert_to_edit` | Roll the app back to a previous edit                               |

### Publishing & domains

| Tool             | What it does                                                                  |
| ---------------- | ----------------------------------------------------------------------------- |
| `publish_app`    | Publish an app to production — only called when you explicitly ask to go live |
| `get_deployment` | Get the deployment status, live URL, and connected domains                    |
| `list_domains`   | List the custom domains registered to a workspace                             |
| `connect_domain` | Connect a custom domain to a published app (returns the DNS records to set)   |

Builds are asynchronous: `create_app` and `send_message` return immediately, and the agent follows up with `wait_for_build` or `get_build_status` until the build completes. Building an app does **not** publish it — apps are fully previewable before going live.

## Build an app end to end

<Steps>
  <Step title="Create">
    Ask your agent to build something. It calls `create_app` with your description and gets back an app ID.
  </Step>

  <Step title="Wait for the build">
    The agent calls `wait_for_build` until the build completes — typically a few minutes, longer for complex apps.
  </Step>

  <Step title="Iterate">
    Request changes in plain language. Each one becomes a `send_message` call followed by another build. Use `get_diff` to review exactly what changed.
  </Step>

  <Step title="Publish">
    When you're happy, ask to go live. The agent calls `publish_app`, then checks `get_deployment` until your app's URL is ready.
  </Step>
</Steps>

## Example prompts

```
Create 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, wait for the build,
and show me the diff.
```

```
Something broke after the last change — show me the edit history
and revert to the version before it.
```

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

## Plan features and limits

The MCP server is available on the **Pro plan**. The check applies per workspace: every workspace a tool acts on must be on a Pro plan, so if you're a member of several workspaces, your agent can only work in the Pro ones. `list_teams` always works, so the agent can discover which of your workspaces it can act on.

Calling a tool against a workspace that isn't on a Pro plan returns a `FORBIDDEN` error explaining that the plan doesn't include the MCP server.

Requests are rate limited per account: **120 read calls** and **20 write calls** per minute. When a limit is hit, the tool returns a `RATE_LIMITED` error with a retry delay, and well-behaved agents back off automatically.

## Permissions and safety

<Warning>
  A connected client acts **as you**. It can see every workspace you're a member of, and builds it triggers consume real credits — the same as working in the Macaly editor yourself.
</Warning>

* **Builds cost credits.** Every `create_app` and `send_message` consumes credits from the workspace it runs in. Check balances with `get_usage`.
* **Publishing is never automatic.** The server instructs agents to call `publish_app` only when you explicitly ask to go live.
* **Destructive actions are flagged.** `delete_app` and `revert_to_edit` are marked destructive, so most clients ask for confirmation first. Deleting a published app over MCP is blocked entirely — unpublish it first.
* **Your account, your control.** Disconnect the server anytime from your client's connector settings to revoke its access.

## Troubleshooting

* **Sign-in window doesn't appear:** make sure your client supports remote MCP servers with OAuth, and that you added the full URL including the `/api/mcp/mcp` path.
* **A tool returns FORBIDDEN:** the workspace you're acting on isn't on a Pro plan (the MCP server requires Pro), or you're passing a `teamId` for a workspace you're not a member of.
* **`wait_for_build` times out:** that's normal for bigger builds — the build keeps running, and the agent just calls `wait_for_build` again to keep waiting.
* **Need help?** Reach out via the chat in Macaly or check the [FAQ](/en/welcome/faq).