# Ploy for coding agents

You are a coding agent (Claude Code, Codex, Cursor or another) helping someone use Ploy. Ploy is an AI marketing platform that builds, hosts and grows websites. It has a remote MCP server and a CLI. Pick the path from what the user has:

| The user has | Use | First step |
| --- | --- | --- |
| Nothing yet, or an idea | Ploy MCP | `ploy_get_started`, then `ploy_start` with the user's brief |
| A .zip of a site (up to 20 MB) | Ploy MCP | `ploy_upload_url` for the zip, then `ploy_start` with its fileId |
| A live site at a URL | Ploy MCP | `ploy_start` with the URL in the message |
| A code repository | Ploy CLI and the ploy-site skill | Install the CLI and the skill, then follow the skill |

Rule of thumb: use the MCP when Ploy's Agent should do the work (new site, zip, URL, edits, data, publishing). Use the CLI when you write the code yourself (a repo, local edits, git sync).

## Connect the Ploy MCP

- Claude Code: `claude mcp add --transport http ploy https://ploy.ai/api/mcp`, then `/mcp`, select ploy, choose Authenticate.
- Codex CLI: `codex mcp add ploy --url https://ploy.ai/api/mcp`. Sign-in opens in the browser. To sign in again later, run `codex mcp login ploy`.
- Cursor: add `"ploy": { "url": "https://ploy.ai/api/mcp" }` under `mcpServers` in `~/.cursor/mcp.json`.

Sign-in is OAuth in the browser; no API key. The user signs in to Ploy (or creates a free account) and approves access. Then call `ploy_get_started`: it lists the workspace's sites and suggests the next step.

## Install the Ploy CLI and the ploy-site skill (when there is code)

    curl -fsSL https://ploy.ai/install.sh | sh
    ploy login

ploy-site skill:
- Claude Code: `/plugin marketplace add Ploy-AI/ploy-tools`, then `/plugin install ploy@ploy`
- Codex: `codex plugin marketplace add Ploy-AI/ploy-tools`, then install `ploy` from `/plugins`
- Any agent: `npx skills add Ploy-AI/ploy-tools`

Run `ploy --help` before you pick commands; the help matches the installed version.

## Start a new site

- MCP: `ploy_get_started`, ask the user one question about the business if you need it, then `ploy_start` with the brief. Check progress with `ploy_read`; the work continues if your session ends.
- CLI, when you will write the code: `ploy site init --name "<name>" --wait`, then `ploy site git clone <folder>` and build in that checkout. `ploy site init --prompt "<brief>" --wait` asks Ploy's Agent to build it instead (uses Ploy AI credits).

## Import a site from a .zip

1. Call `ploy_upload_url` with the zip's filename, type `application/zip` and size. The file must end in `.zip` and be 20 MB or less.
2. Run the returned `curl -T <file> ...` command. Its JSON output has the fileId.
3. Call `ploy_start` with the fileId and a message such as: "Build my site on Ploy from this zip. Keep its pages, copy and images. Do not publish."

Ploy's Agent unpacks the zip and rebuilds the site on Ploy. There is no CLI zip import. A zip over 20 MB: unzip it and use the repository path below, or send the live URL instead.

## Import from a code repository

- Astro repo that meets Ploy's contract: `ploy site init --from <path> --wait`.
- Next.js, Vite/React or other frameworks: your agent ports the code into Ploy's Astro starter with the ploy-site skill. Contract and steps: https://docs.ploy.ai/cli/bring-your-own-repo
- Your agent does the work, so this uses no Ploy AI credits. Code sync is free on every plan.

Steps (full procedure: https://raw.githubusercontent.com/Ploy-AI/ploy-tools/main/skills/ploy-site/references/migration.md):

1. Check the CLI: `ploy --version` and `ploy site git --help`. The help must list `clone` and `sync`. If a command is missing, report the release blocker instead of guessing a substitute.
2. Leave the source repo unchanged. Record its commit, then list every page and dynamic route, redirects, assets, forms, API routes, middleware, environment variables and analytics.
3. Show the user a plan before you create a site or change files: direct import or port, whole site or selected pages, what can't move as-is, any paid features, and how you will test each route.
4. After approval: `ploy site init --name "<name>" --wait`, `ploy site use --id <site-id>`, `ploy site git clone <folder>`. Edit only that checkout.
5. Build and test every route, commit, `git push ployspace HEAD:main`, then `ploy site git sync`. Check the Ploy preview; a successful sync does not prove the preview works.
6. Report the preview URL, the source and Ploy commit IDs, and anything that did not move.

## Move a live site from its URL

`ploy_start` with the URL in the message, for example "Move https://example.com to Ploy". Ploy's Agent maps the pages, agrees a plan with the user, and rebuilds the site. This uses Ploy AI credits.

## Rules

- The user approves sign-in, publishing, payments and domain changes. Send them the dashboardUrl that Ploy returns; you cannot approve for them.
- Do not publish unless the user asks.

## More

- MCP setup for every client: https://docs.ploy.ai/mcp
- CLI and repo migration: https://ploy.ai/cli
- MCP server card: https://ploy.ai/.well-known/mcp/server-card.json
- Everything else: https://ploy.ai/llms.txt
