Macaly MCP Server

The Macaly MCP server lets AI agents manage your Macaly apps programmatically using the Model Context Protocol — 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.

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.

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.

Claude
Claude Code
Cursor
ChatGPT
VS Code

In claude.ai or the Claude desktop app, open Settings → Connectors.
Click Add custom connector.
Enter https://www.macaly.com/api/mcp/mcp and click Add.
Click Connect and approve access in the Macaly window that opens.

Run in your terminal:

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.

Add the server to .cursor/mcp.json (per project) or ~/.cursor/mcp.json (global):

{
  "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.

Open Settings → Connectors (requires developer mode or a plan with custom connectors).
Click Create and enter https://www.macaly.com/api/mcp/mcp.
Approve access in the Macaly window that opens.

Add the server to .vscode/mcp.json:

{
  "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.

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.

Using an API key instead

On the Agency plan, you can authenticate with a Macaly API key instead of OAuth, which is useful for headless agents and automation. Pass the key as a bearer token:

{
  "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.

Media in generated apps

Apps built through the MCP server can include AI-generated images used as design assets — hero visuals, illustrations, background textures, favicons — the same way the Macaly agent creates them in the editor. Stock photo and icon search are available too, so an app can use licensed imagery instead.

AI audio and AI video generation are not available over the MCP server. Music generation, speech synthesis (text-to-speech), and video generation are switched off for builds triggered through a connected client. This keeps the connector within the media-generation rules of the AI client directories it is distributed through.

If you ask for them anyway, the agent builds the app without them rather than failing — a landing page gets a static hero image instead of a generated video background, for example. Speech-to-text transcription stays available, since that analyzes audio rather than generating it. The limit applies only to builds triggered through the MCP server. Working in Macaly directly, music, voiceover, and video generation are available as usual on plans that include them.

Build an app end to end

Create

Ask your agent to build something. It calls create_app with your description and gets back an app ID.

Wait for the build

The agent calls wait_for_build until the build completes — typically a few minutes, longer for complex apps.

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.

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.

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

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.

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.
Builds can reach the public web. When a request calls for it, the build agent searches the internet, fetches pages, takes screenshots, and scrapes public data. create_app and send_message are annotated as open-world for that reason, so clients can surface it before running them.
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.

Connections

Integrations

Why connect the MCP server

What you need

Connect your client

Using an API key instead

Available tools

Workspaces & credits

Apps

Building & iteration

Code inspection

Publishing & domains

Media in generated apps

Build an app end to end

Example prompts

Plan features and limits

Permissions and safety

Troubleshooting

​Why connect the MCP server

​What you need

​Connect your client

​Using an API key instead

​Available tools

​Workspaces & credits

​Apps

​Building & iteration

​Code inspection

​Publishing & domains

​Media in generated apps

​Build an app end to end

​Example prompts

​Plan features and limits

​Permissions and safety

​Troubleshooting

Why connect the MCP server

What you need

Connect your client

Using an API key instead

Available tools

Workspaces & credits

Apps

Building & iteration

Code inspection

Publishing & domains

Media in generated apps

Build an app end to end

Example prompts

Plan features and limits

Permissions and safety

Troubleshooting