--- title: "Tools" description: "The tools an agent can call to build, change and publish a site, and the scope each one needs." canonical: "https://atelier201.com/docs/mcp/standard-tools" updated: "2026-11-06" --- # Tools The [generated operation coverage](/docs/api/surfaces) maps REST, CLI, and MCP. For discovery, read `atelier201://operations`, then `atelier201://operations/{operation_id}` for one full contract. The full document is `atelier201://openapi`. Unknown tool arguments are rejected instead of silently ignored. `get_workspace` reads the uncommitted files and diff without running bash. It uses the same `sites:write` permission as the workspace REST endpoint and changes neither the draft nor the published site. The tools are shaped around the work an agent does, not around endpoints. Their descriptions are written by hand, because a model reads them as its whole interface: each one says what it changes, whether visitors can see it, and what to call next. Only the tools your credential's scopes allow are offered, so a connection without `sites:publish` never sees `publish_site`. One tool spends credits, `generate_media`, and only with the `media:generate` permission. ## The order of work 1. `get_account`, then `list_sites` to get a `site_id`, or `create_site`. 2. `edit_text` for any visible text, `set_field` for a field you know, `save_entry` and `save_entries` for entries, `save_singleton theme` for the look. Use `read_file` and `edit_files` (or `bash` then `commit_workspace`) only to change code. 3. Every save starts its build and returns `build`: `get_build` with that id waits (50 s by default) and answers when it is `ready` or `failed`. With `preview: true`, a ready build comes with a link to open; without a browser, `read_page` reads the pages. `build_site` is for building a given revision or trying again. 4. `show_site`: in a host that displays apps (Claude, ChatGPT), the owner sees the draft live in a card, with Publish. Elsewhere, `share_preview` and give them the link. 5. `review_publish`, and `publish_site` only after the owner approves. ## Sites and content | Tool | Scope | What it does | | --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `list_sites`, `get_site` | `sites:read` | Read the workspace's sites. | | `create_site` | `sites:write` | Create a site from the starter and start its first build. | | `rename_site` | `sites:write` | Change the name shown in Atelier201. | | `get_content_model` | `sites:read` | Read collections and singletons with their JSON Schemas. | | `list_entries`, `get_entry` | `sites:read` | Read entries of a collection. | | `save_entry` | `sites:write` | Write one entry, validated. A new entry starts as a draft. | | `delete_entry` | `sites:write` | Remove an entry from the draft. | | `get_singleton` | `sites:read` | Read business details, theme or navigation. | | `save_singleton` | `sites:write` | Replace a whole singleton, validated. | | `set_field` | `sites:write` | Change one field by its `data-atelier201-field` address. | | `apply_site_plan` | `sites:write` | Write a first version or a large rework in one call: business details, theme, navigation, entries and pictures, validated together. | | `place_image` | `sites:write` | Put a picture in an image field (a stock description, a chosen result or a site file) with its alt text, in one call. | | `edit_text` | `sites:write` | Change a text wherever it is written (content or code), given as it reads on the page. | ## Files, history and changesets | Tool | Scope | What it does | | -------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------- | | `list_files`, `read_file`, `read_files`, `search_files` | `sites:read` | Read the project. `read_file` returns the hash to send as `expected_hash`; `read_files` reads up to 30 files in one call. | | `edit_files` | `sites:write` | Apply put, delete and move operations as one history entry. | | `get_workspace` | `sites:write` | Read uncommitted files and their diff without running a command. | | `open_changeset`, `stage_changes`, `commit_changeset`, `abandon_changeset` | `sites:write` | One history entry from several calls. | | `list_history`, `compare_revisions` | `sites:read` | Read the history. | | `restore_revision` | `sites:write` | Make the draft match an earlier revision, as a new entry. | ## Media | Tool | Scope | What it does | | ---------------------- | ---------------- | ------------------------------------------------------------------------------------------ | | `list_media` | `sites:read` | Read uploaded files and the storage left. | | `upload_media` | `sites:write` | Upload a base64 file, 5 MB at most through MCP. | | `delete_media` | `sites:write` | Remove a file from the next builds. | | `search_stock_media` | `sites:read` | Search free stock photos and videos (Pixabay). | | `import_stock_media` | `sites:write` | Copy one result into the site's media, with its credit. | | `list_media_models` | `sites:read` | The AI image and video models and their prices in credits. | | `generate_media` | `media:generate` | Make an image or video with AI. Spends credits: `estimate_only` first, then `max_credits`. | | `get_media_generation` | `sites:read` | Where a generation stands, and its file once done. | ## Build and preview | Tool | Scope | What it does | | ------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `build_site` | `sites:write` | Compile the draft. Returns a `queued` build at once. | | `list_builds`, `get_build`, `get_build_log` | `sites:read` | Read builds and the log of a failed one. `get_build` takes `wait` (answer when the build finishes) and `preview` (a link to a ready build; needs `sites:write`). | | `read_page` | `sites:read` | One page of a build as a visitor reads it, with the issues a quick review would catch: for an agent without a browser. | | `show_site` | `sites:read` | Open the site card, an MCP app: the draft live (it reloads by itself after each build), a picture of the home page when the host cannot frame it, the Publish button (Go live, Publish changes) and Comment, which sends "change this" about an element back to the conversation. Without `sites:write`, the card shows the picture only. | | `share_preview` | `sites:write` | Create a private link to a build, 7 days by default. | | `list_previews` | `sites:read` | Read preview links. | | `revoke_preview` | `sites:write` | Stop a preview link. | ## Publish and domains These change what visitors see. Ask the owner first. | Tool | Scope | What it does | | ---------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `review_publish` | `sites:read` | Show what would go live, what blocks it and the `expected_generation`. | | `publish_site` | `sites:publish` | Make a build live. | | `rollback_site` | `sites:publish` | Serve an earlier publication again. | | `unpublish_site` | `sites:publish` | Take the site offline. | | `delete_site` | `sites:publish` | Delete a site for good. `confirm_name` must be its name or slug; a published site needs `delete_published: true`. Cannot be undone. | | `list_publications` | `sites:read` | Read the publication history. | | `get_site_analytics` | `sites:read` | Read a site's visitor numbers over a period. | | `list_domains` | `sites:read` | Read domains and the DNS records each still needs. | | `add_domain`, `check_domain` | `domains:write` | Connect a domain, and check its DNS records. | | `remove_domain` | `domains:write` | Disconnect a domain. | | `set_main_domain` | `domains:write` | Redirect the other addresses to one, and rebuild. | Publishing, rolling back, taking offline and changing domains also need a workspace admin. Binary project import and export use the [REST API](/docs/api/overview) or [CLI](/docs/cli/commands); MCP agents read and change individual files instead. ## Account | Tool | Scope | What it does | | -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `get_account` | `account:read` | Read the workspace, the plan and the scopes of this credential. | | `get_credit_balance` | `account:read` | Read the credit balance and every grant. | | `get_usage` | `usage:read` | Read credit usage over time. | | `list_skills` | none | List the manuals: how to create a site, edit content, change the design, import data, fix a build, publish. Call it before you build. | | `get_skill` | none | Read one manual in full, as Markdown. | | `send_feedback` | none | Report something wrong or missing in the API, CLI or MCP server. | ## Writing safely Send the hash from `read_file` as `expected_hash` on every file you change. If someone changed it since, the whole change is refused with a `conflict` error and nothing is written. Read the files again, apply your change on top and retry. `publish_site` takes the `expected_generation` from `review_publish` and is refused if the site was published since.