Yosk MCP API
Yosk SiteBuilder is an agent-first website builder: every site-building operation is exposed as a tool on a Model Context Protocol (MCP) server, and AI agents build, verify and publish sites by calling these tools. This page is the agent-readable specification of that API.
Endpoint
Streamable HTTP transport, JSON-RPC 2.0.
Authentication
OAuth 2.1 authorization code flow with PKCE (Kinde). An unauthenticated request to
the endpoint returns 401 with a WWW-Authenticate header pointing at the OAuth
protected-resource metadata; MCP clients (Claude Code, Claude Desktop, OpenCode) run
the OAuth flow automatically on that challenge. The public client is yosk-mcp-prod
(client_id
Canonical workflows
The initialize handshake response carries server instructions describing the preferred workflows summarized here.
create_site makes a site; every later tool addresses it by its siteKey.
A whole-site import from a design zip goes through begin_file_upload
(kind=source), an HTTP upload to the returned presigned URL, then
complete_file_upload. The base64 submit_source path is
for small or test imports only.
create_page makes the slug; edit_markup writes a whole
region's HTML and CSS fanned out across the desktop, tablet and mobile
breakpoints, with the design's media queries kept in the css parameter. The
surgical tools are reserved for targeted edits, with validate_markup
and diff_markup around writes.
get_served_page returns the emitted page documents;
render_check runs computed-style checks against the served page.
publish_page makes one page live and keeps its previous
live version as the page's revert snapshot;
revert_page restores it. Products are immediate:
set_product_visibility shows or hides one for visitors.
Deployment model
Sites live on the builder instance the agent is connected to and are served at /s/{siteKey}/{slug} on that instance. A site created on a local or QA instance is reachable only there; a 404 for it on yosk.ai is expected, not a failure. The portal at the instance origin is the human preview surface.
Tool surface
| Tool | What it does |
|---|---|
list_ | List all sites on this builder instance, the starting point before working on a site. |
create_ | Create a new empty site on this builder instance; every later tool addresses it by its siteKey. |
delete_ | Delete a site and all of its content; destructive, so it requires confirm=true because the tool is non-interactive. |
get_ | Return a site's editor bootstrap (site key, pages, values and assets) before editing it. |
create_ | Create an empty page, then build its body region with edit_markup - create_page only makes the slug. |
rename_ | Rename a page and rewrite the internal links that point at it. |
delete_ | Delete a page (the index page is protected) without touching links that point at it. |
submit_ | Submit a small or test design zip as base64 for intake; for a real whole-site import use begin_file_upload (kind=source), upload over HTTP, then complete_file_upload. |
begin_ | Start a presigned upload session (kind=source for a whole-site import, kind=asset for an asset), upload the file to the returned URL, then call complete_file_upload. |
complete_ | Finish a begin_file_upload session: source runs intake and returns the report, asset registers the file and returns its reference. |
get_ | Return the persisted intake report (skipped kinds and findings) for an imported site. |
get_ | Return all content values for a site, truncated around 100 KB with a marker. |
get_ | Return one content value by key ({pageId}:{id} or bare {id}). |
update_ | Update one existing content value with kind validation and sanitisation; ids cannot be created here - write the region with edit_markup to add content. |
list_ | List a site's uploaded assets before referencing or deleting them. |
upload_ | Upload a small asset as base64 (up to 25 MB decoded); use begin_file_upload with kind=asset for larger files. |
delete_ | Delete an asset; references that still use it are guarded. |
get_ | Read one region's markup digest (version, sizes, warnings) before editing; set digestOnly to false to include html and css. |
edit_ | Write a whole region's HTML and CSS and fan the same write out to the desktop, tablet and mobile breakpoints (options.breakpoints) - the way to build a page; keep the design's media queries in the css parameter and reach for the surgical tools only for targeted edits. |
query_ | Query elements in one region's HTML by selector or data-yosk-id, returning byte spans and a bounded context window. |
query_ | Query CSS rules by selector, declared property and media, returning byte spans and a bounded context window. |
validate_ | Validate a fragment or the stored markup around a write. |
diff_ | Diff two breakpoints' markup for one region and scope, to confirm a fan-out landed consistently. |
get_ | Return the emitted (served) page documents - verify writes here, then run render_check for computed styles. |
upsert_ | Apply a targeted CSS rule edit (replace by exact selector, else insert); use edit_markup for whole-region writes. |
delete_ | Delete one CSS rule as a targeted edit; use edit_markup for whole-region writes. |
insert_ | Insert an HTML fragment beside a target element as a targeted edit; use edit_markup for whole-region writes. |
replace_ | Replace one target element with an HTML fragment as a targeted edit; use edit_markup for whole-region writes. |
update_ | Set or remove attributes on a target element as a targeted edit; use edit_markup for whole-region writes. |
remove_ | Remove a target element, reporting the value bindings it carried; use edit_markup for whole-region writes. |
publish_ | Publish one page: the draft page becomes its live version and the current live version becomes its revert snapshot. Shared chrome ships with the page that publishes. |
revert_ | Restore one page to its version before its last publish, consuming that page's snapshot. A first-published page is unpublished. |
export_ | Export the owner build for a site as a task, then poll get_export_status for the result. |
get_ | Poll an export_site operation by operation id. |
render_ | Run computed-style checks against the served page, then poll render_check_status; exportFailed means the backend export failed and is independent of publish state, not a content failure. |
render_ | Poll a render_check operation by operation id; exportFailed is a backend export failure, not a content failure. |
list_ | List a site's products with their stored hidden/deleted flags before editing one. |
get_ | Read one product by id. |
create_ | Create an untitled product (BR-135); update_product titles it, which derives its slug and detail page. |
update_ | Update a product's fields from a JSON object; absent fields keep their stored value, the price is a decimal display string and the description is sanitised HTML. |
delete_ | Soft-delete a product: it leaves the listing and its detail URL stops resolving immediately, and stays restorable. |
restore_ | Restore a soft-deleted product. |
set_ | Show or hide a product for visitors immediately; a hidden product leaves the listing and its detail route serves 404. |
get_ | Read one product's detail layout (html, css, version, isCustom) before editing; isCustom false means the inherited product template renders. Set digestOnly to false to include html and css. |
edit_ | Write one product's detail layout (MarkupSafety-validated) and regenerate its document; both html and css empty reset to the inherited product template. |
query_ | Query elements in a product's layout HTML by selector or data-yosk-id, returning byte spans and a bounded context window. |
validate_ | Validate a fragment or the stored product layout without saving. |
diff_ | Diff a product's current layout against the inherited product template; empty when it uses the template unchanged. |