Tools
The tools an agent can call to build, change and publish a site, and the scope each one needs.
The generated operation coverage 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
get_account, thenlist_sitesto get asite_id, orcreate_site.edit_textfor any visible text,set_fieldfor a field you know,save_entryandsave_entriesfor entries,save_singleton themefor the look. Useread_fileandedit_files(orbashthencommit_workspace) only to change code.- Every save starts its build and returns
build:get_buildwith that id waits (50 s by default) and answers when it isreadyorfailed. Withpreview: true, a ready build comes with a link to open; without a browser,read_pagereads the pages.build_siteis for building a given revision or trying again. show_site: in a host that displays apps (Claude, ChatGPT), the owner sees the draft live in a card, with Publish. Elsewhere,share_previewand give them the link.review_publish, andpublish_siteonly 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 or CLI; 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.