https://api.platformdtc.com/mcp/theme — MCP Streamable HTTP (protocol version
2025-06-18): JSON-RPC over POST, optional server-sent events on GET. Authentication is
OAuth 2.1, or a static sq_agt_* key in Authorization: Bearer.
Each tool is a thin wrapper over one Agent Gateway /themes endpoint,
called with your token. Scopes, audit logging, idempotency and rate limits are applied once, by the
Gateway — a tool can do exactly what the same call over REST can do, and nothing more.
The server’s instructions give the agent the working loop:
manifest → read → write → check → preview → publish.
Tools
Every result is the Gateway’s
data object; a
failure carries the Gateway’s message and error_code.
list_themes
Lists the store’s themes. No parameters. Returns{ themes: Theme[] } — each with id, name,
role (main, unpublished or development), builder_version, timestamps, expires_at
(development themes only), editor_url and preview_url.
create_dev_theme
Creates a development theme as a copy of another theme.
Returns the new
Theme. A development theme expires 7 days after its last change. When the store
already holds its limit of development themes (10 by default), the call fails with 409 THEME_LIMIT:
reuse or delete one first.
get_theme
delete_theme
Deletes adevelopment theme. The live theme is refused with 409 THEME_IS_LIVE, and an
unpublished theme with 409 THEME_NOT_DEVELOPMENT — the merchant deletes those in the dashboard.
get_theme_manifest
Sized for an agent’s context: the editable files (template_data, merchant) with size and
checksum (sha256 hex); platform_paths, the platform-owned paths an agent must not write; the
limits; and the list of section_types and block_types available in the theme (type, name,
presets), including your custom sections. Settings schemas are not included — use
get_section_schemas. The REST endpoint GET /themes/{id}/manifest still returns the full manifest.
read_theme_files
Returns{ files: [{ path, checksum, encoding, content }] }. Text files are utf8; images and fonts
are base64. At most 400 files per read.
write_theme_files
Writes up to 50 files, each up to 2 MiB, to a development or unpublished theme. The live (main)
theme is refused with 409 THEME_IS_LIVE: make the change in a development theme and publish it.
checksum_before is the checksum you last read. If the file has changed since — the merchant saved
in the editor, or another agent wrote it — that file is refused with CONFLICT instead of
overwriting their change. Send it on every edit of an existing file.
Returns a WriteResult:
user_errors; the rest
are written atomically and recorded as one version. If every file fails, nothing is written and
version_id is null. Error codes: PLATFORM_OWNED, IGNORED_PATH, INVALID_PATH, TOO_LARGE,
CONFLICT, INVALID_JSON, INVALID_TEMPLATE, NOT_FOUND.
delete_theme_files
Returns a
WriteResult. The same ownership rules apply: a platform-owned file cannot be deleted, and
the live theme is refused with 409 THEME_IS_LIVE.
check_theme
Runs theme check.
Returns
{ ok, errors, warnings }. One check runs per store at a time; a busy validator answers
429 CHECK_BUSY with Retry-After: 5 — wait and call again, and do not run checks in parallel.
preview_theme
Returns{ url, expires_at } — a temporary preview link to open in a browser.
publish_theme
Returns
{ job_id, status } where status is queued, or pending_approval when the store requires
approval. If a publish of the theme is already queued, waiting for approval or running, the call
returns that job with "existing": true (HTTP 200) instead of starting another. A failing theme
check returns CHECK_FAILED with the check result; a busy validator returns 429 CHECK_BUSY. See
Scopes and approvals.
get_publish_status
The same publish status the dashboard shows for the theme.list_theme_versions
Returns{ versions: [{ id, created_at, message, author }] }. Agent writes are authored
agent:<key name>.
rollback_theme
Restores a development theme’s files to a version. The live theme is refused with409 THEME_IS_LIVE.
Returns a
WriteResult. Rolling back a development theme does not change the live store until it is
published.
get_section_schemas
Settings schemas for the types you name — platform and custom. Each setting is compact:id, type,
default, the allowed option values, and min/max/step. A section lists the blocks it accepts
(type, name, limit); a block it defines inline has local: true and is fetched as
"<section>:<block>" (returned in local_blocks). Types that do not exist come back in
unknown_types. Without types, the tool returns just the list of available types. Read these before
writing a template instead of guessing setting ids.