leaf mcp lets MCP clients such as Claude Desktop, Claude Code, Cursor, and other clients list, create, deploy, roll back, and delete your sites through the leaf CLI you already use. It runs as a local stdio server and exposes tools and LeafCloud documentation resources to the assistant.

LeafCloud is in private beta; invites are sent by email.

Requirements

Install leaf and sign in once by running leaf login in a terminal. Alternatively, set LEAF_TOKEN to an API key in the MCP server’s environment; the assistant does not see the token. For an agent, create a deploy-only key restricted to one site with an expiry, as shown in Use with AI agents.

Configure a client

Each configuration starts the local leaf mcp process. Replace leaf with its full executable path if the client cannot find it.

Claude Desktop

Add this entry to claude_desktop_config.json under mcpServers, then restart Claude Desktop:

{
  "mcpServers": {
    "leafcloud": {
      "command": "leaf",
      "args": ["mcp"]
    }
  }
}

Claude Code

Run this in a terminal:

claude mcp add leafcloud -- leaf mcp

Or register the stdio server from JSON:

claude mcp add-json leafcloud '{"type":"stdio","command":"leaf","args":["mcp"]}'

Cursor

Add this entry to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "leafcloud": {
      "command": "leaf",
      "args": ["mcp"]
    }
  }
}

Other MCP clients

For a generic stdio client, use this server entry:

{
  "command": "leaf",
  "args": ["mcp"]
}

To use an API key instead of the saved leaf login credentials, add an env object to the server entry in your client config. Keep this local config private and do not commit it:

"env": {
  "LEAF_TOKEN": "your-deploy-only-key"
}

Use a deploy-only key for one site and set an expiry. The token is passed to the local CLI process; it is not included in prompts, tool arguments, or results.

Available tools

The server provides these tools. Read-only tools do not change sites. deploy changes a site when dry_run is false; delete_site is destructive.

Tool	Arguments	What it does	Effect
whoami	None	Returns account email, access state, and credential type. Scopes and site restrictions apply to API keys only.	Read-only
list_sites	None	Lists sites with their URL, live deploy, and propagation status.	Read-only
get_site	name	Reads one site’s URL, live deploy, and propagation status.	Read-only
suggest_site_names	count (optional, 1–10; default 3)	Suggests available names; suggestions do not reserve names.	Read-only
create_site	name	Creates a site.	Changes things
deploy	path, optional site, optional dry_run (default false)	Builds and uploads the project folder, or inspects it without uploading when dry_run is true. Always dry-run first, show the user the returned file_list, and deploy only after they agree.	Changes things, unless dry run
list_deploys	site	Lists that site’s deployment history.	Read-only
rollback	site, deploy_id	Makes a retained deployment live for the site.	Changes things
usage	None	Returns this account’s current limits and usage. Limits differ by account; call this instead of assuming any number.	Read-only
delete_site	name, confirm	Permanently deletes a site; confirm must exactly match name.	Destructive

Documentation resources

The server also exposes two read-only resources:

URI	Contents
leafcloud://docs/quickstart	Getting started with sites and deploys.
leafcloud://docs/frameworks	Framework detection and build output guidance.

Safety

• Do not put secrets in prompts or tool arguments. Tokens are not included in tool results.
• delete_site requires confirm to equal the site name and carries MCP’s destructive-tool annotation, which supported clients can use to ask before running it.
• deploy refuses hidden project or output roots, roots at $HOME or its ancestors, roots under system directories, and folders without a top-level index.html unless a framework is detected. The output folder must resolve inside the project folder. Hidden files (including .npmrc and .env) and symlinks that resolve outside the output folder are skipped.
• Before publishing, deploy scans exactly the manifest file set for private-key content and credential/key filenames. It refuses the whole deploy and lists detected paths; private-key content scanning reads the first 1 MB of each file. The CLI applies the same scan; leaf deploy --allow-secrets overrides it only when you are sure those files are meant to be public.
• Start with dry_run: true. It returns file_list (up to 200 paths, plus more when truncated) and skipped paths. Show that file list to the user and run a real deploy only after they agree.
• For agents, use a deploy-only key scoped to one site and set an expiry. Keep LEAF_TOKEN in the MCP server’s environment.
• Errors are returned as tool errors with a next step. Sign-in errors direct you to run leaf login or set LEAF_TOKEN. A 403 identifies the site limit, waiting list, or required API key scope and site access; a 409 deploy conflict says to wait for the deploy to finish, and a taken name requires another name; a 429 includes the API message and any retry delay, and says not to loop.

Example prompts

• “Deploy this folder to LeafCloud as a new site and give me the URL.”
• “List my sites and show which deploy is live for each.”
• “Roll back my-site to the deploy before the current one.”
• “How much storage am I using, and what is my quota?”
• “Suggest three available site names.”
• “Delete my-site.”

For deletion, the client should ask you to confirm the exact site name before calling the destructive tool.

Troubleshooting

• Not signed in: Run leaf login in a terminal, or set LEAF_TOKEN to an API key in the MCP server environment.
• 403 Forbidden: Check the API key’s scope and site access. Deploy uses deploy scope; creating or deleting a site uses manage scope. Site limits and waiting-list access are reported directly.
• 409 Conflict: Wait for an in-progress deploy to finish before retrying, or choose another site name if the name is taken.
• 429 Rate limited: Follow the API message and any retry delay. Do not have the assistant retry in a loop.
• The client cannot find leaf: Add the directory containing leaf to the client’s PATH, or set command to the full path from which leaf (macOS/Linux) or where leaf (Windows).