MCP tool reference

Server: 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

Tool	Endpoint	Scope
`list_themes`	`GET /themes`	`read_themes`
`create_dev_theme`	`POST /themes`	`write_themes`
`get_theme`	`GET /themes/{id}`	`read_themes`
`delete_theme`	`DELETE /themes/{id}`	`write_themes`
`get_theme_manifest`	`GET /themes/{id}/manifest`	`read_themes`
`read_theme_files`	`GET /themes/{id}/files`	`read_themes`
`write_theme_files`	`PUT /themes/{id}/files`	`write_themes`
`delete_theme_files`	`POST /themes/{id}/files/delete`	`write_themes`
`check_theme`	`POST /themes/{id}/check`	`read_themes`
`preview_theme`	`POST /themes/{id}/preview`	`read_themes`
`publish_theme`	`POST /themes/{id}/publish`	`publish_themes`
`get_publish_status`	`GET /themes/{id}/publish-status`	`read_themes`
`list_theme_versions`	`GET /themes/{id}/versions`	`read_themes`
`rollback_theme`	`POST /themes/{id}/rollback`	`write_themes`
`get_section_schemas`	`GET /themes/{id}/manifest` (`section_types`, `block_types`)	`read_themes`

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.

Parameter	Type
`name`	string	Required.
`from_theme_id`	string	Theme to copy. Defaults to the live (`main`) 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

Parameter	Type
`theme_id`	string	Required.

delete_theme

Deletes a development 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.

Parameter	Type
`theme_id`	string	Required.

get_theme_manifest

Every file with its owner (template_data, merchant, platform), editable, size and checksum (sha256 hex); the limits; and the section_types and block_types available in the theme, including your custom sections.

Parameter	Type
`theme_id`	string	Required.

read_theme_files

Returns { files: [{ path, checksum, encoding, content }] }. Text files are utf8; images and fonts are base64. At most 400 files per read.

Parameter	Type
`theme_id`	string	Required.
`only`	string[]	Glob patterns, for example `["templates/.json", "theme/custom/*"]`.

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.

Parameter	Type
`theme_id`	string	Required.
`files`	`{ path, content, encoding?, checksum_before? }[]`	`encoding` is `utf8` (default) or `base64`.

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:

{
  "upserted": [{ "path": "templates/index.json", "checksum": "9f2c…" }],
  "deleted": [],
  "user_errors": [
    { "path": "theme/builder2/sections/Hero.tsx", "code": "PLATFORM_OWNED", "message": "…" }
  ],
  "version_id": "…"
}

The batch is validated first. Files with errors are skipped and reported in 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

Parameter	Type
`theme_id`	string	Required.
`paths`	string[]	Required.

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.

Parameter	Type
`theme_id`	string	Required.
`only`	string[]	Check only these paths.

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.

Parameter	Type
`theme_id`	string	Required.

publish_theme

Parameter	Type
`theme_id`	string	Required.

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.

Parameter	Type
`theme_id`	string	Required.

list_theme_versions

Returns { versions: [{ id, created_at, message, author }] }. Agent writes are authored agent:<key name>.

Parameter	Type
`theme_id`	string	Required.

rollback_theme

Restores a development theme’s files to a version. The live theme is refused with 409 THEME_IS_LIVE.

Parameter	Type
`theme_id`	string	Required.
`version_id`	string	Required.

Returns a WriteResult. Rolling back a development theme does not change the live store until it is published.

get_section_schemas

The schemas of the section and block types available in the theme — platform and custom — with their settings, allowed blocks, max_blocks, presets and placement rules. Read these before writing a template instead of guessing setting ids.

Parameter	Type
`theme_id`	string	Required.

Local dev MCP

@platformdtc/dev-mcp is a separate, local stdio server. It never calls PlatformDTC and never touches a store — it helps an agent write a correct theme in a local folder, typically one pulled with the CLI.

claude mcp add platformdtc-dev -- npx -y @platformdtc/dev-mcp

Tool	Parameters	Does
`search_docs`	`query`, `limit?`	Full-text search over this theme documentation and the Builder2 contract, bundled with the server. Results include the docs URL.
`get_section_schemas`	`workspace?`, `type?`	The platform section and block schemas bundled with the server; with `workspace`, also that theme’s custom sections and blocks.
`validate_theme`	`path`, `only?`, `mode?` (`development` or `publish`)	Runs theme check on a local theme folder.
`validate_template_json`	`content`, `path?`	Validates one template, section group or `settings_data.json` document without writing it.
`scaffold_custom_section`	`workspace`, `kind` (`section` or `block`), `type`, …	Writes a typed custom section or block with its schema, then runs theme check on it.

Build with your agent

Theme reference

Tools

list_themes

create_dev_theme

get_theme

delete_theme

get_theme_manifest

read_theme_files

write_theme_files

delete_theme_files

check_theme

preview_theme

publish_theme

get_publish_status

list_theme_versions

rollback_theme

get_section_schemas

Local dev MCP

​Tools

​list_themes

​create_dev_theme

​get_theme

​delete_theme

​get_theme_manifest

​read_theme_files

​write_theme_files

​delete_theme_files

​check_theme

​preview_theme

​publish_theme

​get_publish_status

​list_theme_versions

​rollback_theme

​get_section_schemas

​Local dev MCP

Tools

list_themes

create_dev_theme

get_theme

delete_theme

get_theme_manifest

read_theme_files

write_theme_files

delete_theme_files

check_theme

preview_theme

publish_theme

get_publish_status

list_theme_versions

rollback_theme

get_section_schemas

Local dev MCP