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

https://yosk.ai/mcp

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 4292799415ea4839997b32550bb6a38b); local clients listen on http://localhost:60328/callback.

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_sitesList all sites on this builder instance, the starting point before working on a site.
create_siteCreate a new empty site on this builder instance; every later tool addresses it by its siteKey.
delete_siteDelete a site and all of its content; destructive, so it requires confirm=true because the tool is non-interactive.
get_siteReturn a site's editor bootstrap (site key, pages, values and assets) before editing it.
create_pageCreate an empty page, then build its body region with edit_markup - create_page only makes the slug.
rename_pageRename a page and rewrite the internal links that point at it.
delete_pageDelete a page (the index page is protected) without touching links that point at it.
submit_sourceSubmit 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_file_uploadStart 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_file_uploadFinish a begin_file_upload session: source runs intake and returns the report, asset registers the file and returns its reference.
get_intake_reportReturn the persisted intake report (skipped kinds and findings) for an imported site.
get_valuesReturn all content values for a site, truncated around 100 KB with a marker.
get_valueReturn one content value by key ({pageId}:{id} or bare {id}).
update_valueUpdate one existing content value with kind validation and sanitisation; ids cannot be created here - write the region with edit_markup to add content.
list_assetsList a site's uploaded assets before referencing or deleting them.
upload_assetUpload a small asset as base64 (up to 25 MB decoded); use begin_file_upload with kind=asset for larger files.
delete_assetDelete an asset; references that still use it are guarded.
get_markupRead one region's markup digest (version, sizes, warnings) before editing; set digestOnly to false to include html and css.
edit_markupWrite 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_markupQuery elements in one region's HTML by selector or data-yosk-id, returning byte spans and a bounded context window.
query_cssQuery CSS rules by selector, declared property and media, returning byte spans and a bounded context window.
validate_markupValidate a fragment or the stored markup around a write.
diff_markupDiff two breakpoints' markup for one region and scope, to confirm a fan-out landed consistently.
get_served_pageReturn the emitted (served) page documents - verify writes here, then run render_check for computed styles.
upsert_css_ruleApply a targeted CSS rule edit (replace by exact selector, else insert); use edit_markup for whole-region writes.
delete_css_ruleDelete one CSS rule as a targeted edit; use edit_markup for whole-region writes.
insert_htmlInsert an HTML fragment beside a target element as a targeted edit; use edit_markup for whole-region writes.
replace_htmlReplace one target element with an HTML fragment as a targeted edit; use edit_markup for whole-region writes.
update_html_attrsSet or remove attributes on a target element as a targeted edit; use edit_markup for whole-region writes.
remove_htmlRemove a target element, reporting the value bindings it carried; use edit_markup for whole-region writes.
publish_pagePublish 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_pageRestore one page to its version before its last publish, consuming that page's snapshot. A first-published page is unpublished.
export_siteExport the owner build for a site as a task, then poll get_export_status for the result.
get_export_statusPoll an export_site operation by operation id.
render_checkRun 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_check_statusPoll a render_check operation by operation id; exportFailed is a backend export failure, not a content failure.
list_productsList a site's products with their stored hidden/deleted flags before editing one.
get_productRead one product by id.
create_productCreate an untitled product (BR-135); update_product titles it, which derives its slug and detail page.
update_productUpdate 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_productSoft-delete a product: it leaves the listing and its detail URL stops resolving immediately, and stays restorable.
restore_productRestore a soft-deleted product.
set_product_visibilityShow or hide a product for visitors immediately; a hidden product leaves the listing and its detail route serves 404.
get_product_layoutRead 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_product_layoutWrite one product's detail layout (MarkupSafety-validated) and regenerate its document; both html and css empty reset to the inherited product template.
query_product_layoutQuery elements in a product's layout HTML by selector or data-yosk-id, returning byte spans and a bounded context window.
validate_product_layoutValidate a fragment or the stored product layout without saving.
diff_product_layoutDiff a product's current layout against the inherited product template; empty when it uses the template unchanged.