Builder MCP server
An AI agent can build a store's pages, saved sections and design through the Builder's MCP server. It is one address for every store: https://builder.usethrottle.dev/mcp (Streamable HTTP, POST only, stateless, JSON answers). The store is
chosen by the key you give the agent, or by what you pick when you sign in. What the agent may do is set by its level:
read, draft, publish or full.
@usethrottle/builder-react 0.4.0 or later and @usethrottle/builder-schema 0.2.1 or later. A store still on 0.3.x is not broken by an agent that uses them, but it shows less: interactions are drawn as a plain row of columns, a
countdown is empty, custom CSS is ignored, and a page that contains a saved-section reference fails to render. Upgrade the store first. See Versions.
What this is, if you have never used MCP
MCP (Model Context Protocol) is the standard way to plug a tool into an AI assistant. The Builder is the tool; the assistant (Claude, or the AI in your code editor) is the one that uses it. Once connected, you describe what you want in plain words ("add a winter sale page with a countdown") and the assistant reads your store, makes the change as a draft, looks at the result in a browser, and, if you allowed it, publishes.
Connecting means telling the assistant two things: the address above, and who it is allowed to act as. There are two ways to do that, and you only need one.
| If you use | Connect with | You need |
|---|---|---|
| claude.ai or the Claude desktop app | The address only. You sign in to Throttle and approve. No key. | A Throttle login with access to the store. |
| Claude Code, Cursor, VS Code, Windsurf or any other coding tool | The address and a key. The key is a password you make in the Builder and paste into the tool. | A key from Keys and AI agents in Throttle Builder. |
Connect an AI agent
claude.ai or Claude desktop: the address only
Add a custom connector
In claude.ai or the Claude desktop app, open Settings, then Connectors, then Add custom connector.
Paste the address
Name it Throttle Builder and paste https://builder.usethrottle.dev/mcp as the URL. Leave Advanced settings empty: do not paste a client ID or a secret.
Connect and sign in
Choose Add, then Connect. Throttle opens in a new window: sign in with your Throttle account.
Choose the store and the level
Pick the workspace, the application and the environment where Throttle Builder is installed. Choose the level (see below) and, if you want the agent to write code, the code switch. Choose Approve.
If Claude says it could not connect, wait up to 5 minutes after you added it (Claude takes a moment to recognise a new connector) and connect again. You can change the level later without connecting again, and revoke the connection at any time, in Throttle Builder under Keys and AI agents.
Coding tools: the address and a key
Make a key
In Throttle Builder, open Keys and AI agents, then Connect an AI agent. Choose a level (start with Draft) and create the key. It is shown once, so copy it now. Keys do not expire; you can revoke one at any time.
Put the address and the key in your tool
Copy the snippet for your tool below. The Builder shows the same snippets with your key already filled in, with a Copy button.
Check it
Each tool has a line that says it worked. If it does not, see Troubleshooting below, or use Test connection on the same screen.
Give the agent a browser
So that it can look at what it builds, add one browser tool (next section). This is the step that makes the result good.
In every snippet, tb_sk_PASTE_YOUR_KEY stands for your key. Use a secret key (tb_sk_...); a
publishable key (tb_pk_...) never works here.
Claude Code
Run this once in a terminal, from the folder you work in. Then run claude mcp list: throttle-builder should say Connected.
claude mcp add --transport http throttle-builder https://builder.usethrottle.dev/mcp --header "Authorization: Bearer tb_sk_PASTE_YOUR_KEY" Cursor
Save as ~/.cursor/mcp.json (your own user config, which is not part of any project), then restart Cursor. In Cursor Settings, MCP: throttle-builder shows a green dot and its tools.
{
"mcpServers": {
"throttle-builder": {
"url": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer tb_sk_PASTE_YOUR_KEY" }
}
}
}
Want it in a project file (.cursor/mcp.json)? Those files are often committed, so keep the key out of it: set an environment variable named THROTTLE_BUILDER_KEY to your key and use this.
{
"mcpServers": {
"throttle-builder": {
"url": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer ${env:THROTTLE_BUILDER_KEY}" }
}
}
} VS Code
Save as ~/.copilot/mcp-config.json (VS Code's user-level Copilot config, not part of any project), then run MCP: List Servers and check throttle-builder is listed (start it if it shows Stopped). Copilot Chat in Agent mode then lists its tools.
{
"mcpServers": {
"throttle-builder": {
"type": "http",
"url": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer tb_sk_PASTE_YOUR_KEY" }
}
}
}
Want it in the project? Save this as .mcp.json in the workspace root. Project files are often committed, so it reads the key from an environment variable named THROTTLE_BUILDER_KEY: set it to your key. VS Code reads an existing .mcp.json as it is; to add one with MCP: Add Server, turn on the setting chat.mcp.workspaceRootConfig.enabled.
{
"mcpServers": {
"throttle-builder": {
"type": "http",
"url": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer ${THROTTLE_BUILDER_KEY}" }
}
}
}
For VS Code's older MCP setup (deprecated; VS Code plans to remove it in February 2027), use .vscode/mcp.json or MCP: Open User Configuration. The project form asks for the key instead of storing it.
{
"servers": {
"throttle-builder": {
"type": "http",
"url": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer ${input:throttle-builder-key}" }
}
},
"inputs": [
{
"type": "promptString",
"id": "throttle-builder-key",
"description": "Throttle Builder key",
"password": true
}
]
} Windsurf
Add to ~/.codeium/windsurf/mcp_config.json, then refresh MCP in Cascade. Cascade shows throttle-builder with its tools.
{
"mcpServers": {
"throttle-builder": {
"serverUrl": "https://builder.usethrottle.dev/mcp",
"headers": { "Authorization": "Bearer tb_sk_PASTE_YOUR_KEY" }
}
}
} Other MCP clients
Any client that speaks Streamable HTTP MCP and can send a header: give it the address and this one header. To try the key from a terminal, the MCP inspector prints the tools the key allows.
URL: https://builder.usethrottle.dev/mcp
Header: Authorization: Bearer tb_sk_PASTE_YOUR_KEY npx @modelcontextprotocol/inspector --cli https://builder.usethrottle.dev/mcp \
--transport http --header "Authorization: Bearer tb_sk_PASTE_YOUR_KEY" --method tools/list Let your agent see its work
An agent that cannot look at a page is guessing. Throttle never takes screenshots for the agent: there is no server-side screenshot. Instead the agent asks for a preview link, opens it in a browser of its own, looks, and fixes what it sees. So add one browser tool to your agent. Start with Playwright MCP.
| Browser tool | Why choose it | How to add it (Claude Code) |
|---|---|---|
| Playwright MCP | Start here. It opens a clean browser the agent controls, at any width, with nothing of yours in it. | claude mcp add playwright -- npx @playwright/mcp@latest |
| Claude in Chrome | Uses your own Chrome, so the agent sees pages the way you do, signed in as you. | Needs a direct Anthropic plan (Pro, Max, Ultra, Team or Enterprise) and Claude Code signed in with /login. Install the Claude in Chrome extension (version 1.0.36 or later) in Chrome or Edge, then start Claude Code with claude --chrome (or run /chrome and choose Enabled by default). |
| Chrome DevTools MCP | Adds what a developer sees: the console, network requests and performance. | claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest |
In another tool, add the same server in its MCP settings: the command is npx with @playwright/mcp@latest (or chrome-devtools-mcp@latest) as its argument.
What the preview call returns
get_preview_url answers three links, and the widths to check:
{
"draftUrl": "https://builder.usethrottle.dev/preview?token=...",
"liveUrl": "https://your-store.com/pages/winter-sale",
"storePreviewUrl": "https://your-store.com/pages/winter-sale?throttle_builder_preview=...",
"widths": [390, 768, 1280],
"expiresAt": "..."
} -
draftUrl: the draft drawn by the Builder itself, readable without signing in, valid for 12 hours, and markednoindex. It is responsive, so the agent resizes its own window to 390, 768 and 1280 px and checks each. There is nodeviceinput: the agent chooses the size. -
storePreviewUrl: the same draft drawn by your store, with your store's own fonts and widgets. It lasts 1 hour; ask again for a new one. It isnullwhen the site has no store address. Code widgets run only here: the Builder's own preview draws a code widget's markup and CSS with a "Runs on your store" badge and never runs its script. liveUrl: the page as shoppers see it now, ornullfor a page never published.
A first request to try
Use the throttle-builder tools. Read my site and pages first. Then make a page called "Winter sale"
with a hero, a four-product grid and a countdown to 2026-12-24 18:00 (my time). Check it in your
browser at 390, 768 and 1280 px wide and fix anything that looks wrong. Levels, and the code switch
Every key and every connection has one level, chosen when you make the key or approve the connection, and a separate code switch (off unless you turn it on). The level, not a list of scopes, is what limits the agent. The tool list the agent sees is filtered by its level, every call is checked again, and a lowered level applies on the very next call.
| Level | What it means | Scopes it holds |
|---|---|---|
| Read | Reads your site and pages. Changes nothing. | the four :read scopes |
| Draft | Edits drafts. Never publishes. | Read plus the four :write scopes |
| Publish | Edits and publishes pages and site settings. Never publishes page deletions, saved sections or releases. | Draft plus pages:publish |
| Full | Publishes everything, including page deletions, saved sections and releases. | Publish plus releases:read and releases:write |
Code widgets. The code switch lets an agent write JavaScript that runs on your store pages. It needs a level first (a key cannot have code without one), and it does nothing until a person also turns code widgets on for the site: see Code widgets. Code can read and change anything on your store pages.
Who may grant what
The workspace owner, and the person who first installed Throttle Builder (while they still have Builder access), may grant any level and the code switch. Anyone else with Builder access (a workspace admin, or an
application admin or developer) may grant up to Publish, without code. Any other member may grant Read only. A request above that is refused: 403 LEVEL_NOT_ALLOWED on a key, 403 builder_level_not_allowed on the consent screen.
What a level cannot do
-
A tool that changes what shoppers see without a page publish (
set_widget_status,delete_widget,delete_media) needs Publish. A Draft key does not see these tools, and calling one anyway is403 PERMISSION_REQUIRED; the answer names what is missing (level:publish,level:fullorcode). Tell the person; do not retry. - Page deletions are staged by Draft and Publish and published only by Full. A saved section is published only by Full, because it changes every page that uses it. Releases (build-time stores) need Full.
- Catalog data is read-only to agents. No tool, route or level writes products, collections or categories.
- The store connection is people-only. The
connectionssection of the site settings (the Throttle publishable key) is not editable by an agent and is never shown to one:get_siteonly says whether it is set. A widget that a merchant turned off stays merchant-only. Keys, connected assistants and their levels are never managed by an agent.
Keys you made before levels
A key made before levels existed keeps exactly the scopes and the Allow publishing switch it had. If they match a level exactly it shows as that level; otherwise it shows as Custom (legacy) with its exact scopes, unchanged
until you edit it. A body with scopes when making a key is refused (422 SCOPES_REPLACED_BY_LEVEL): ask for a level.
How an agent works on your store
The server tells every agent the same working order, so you do not have to:
- Read the site:
get_site,list_pages,get_pagewithoutline: true,list_widgets. - Make the change, passing the
draftRevit last read asbaseRevso it never overwrites someone else's edit. - Call
validate_pageand fix every error. - Call
get_preview_url, opendraftUrlin its own browser at 390, 768 and 1280 px, and fix what looks wrong. Code widgets run only onstorePreviewUrl. - With the publish tool (Publish or Full), it publishes when the work is correct. It does not wait for you. Without it (Read or Draft), it stops and gives you the preview link.
If a tool answers PERMISSION_REQUIRED, the agent tells you which permission the key needs and does not retry.
Undo
Every draft change by an agent or a person is in a journal (the newest 100 per document, and for the site settings). list_changes lists it, newest first. undo_change undoes the latest
undoable change, and repeated calls walk further back, as long as nothing else has changed the draft since (otherwise DRAFT_CONFLICT: undo the newer change first). An undo is itself listed but cannot be undone: make the edit again. Undo cannot step back past a version restore, a
page deletion or the upgrade of a page with older widgets. Nothing is published by an undo.
What an agent can build
- Pages, header, footer and slots, with every widget, data binding and responsive override, and the whole site design (theme, brand, menus, announcement, SEO, wording, languages, routes, store address, and custom CSS). See the document schema.
- Interactions and animation: a section can be tabs, an accordion, a carousel or a show and hide, with its columns as the panels; a
basic.countdownwidget counts down to a date; any node can animate in on scroll. See the widget guideline. - Saved sections: one section kept once and used on many pages (
create_saved_section,insert_saved_section,detach_saved_section,delete_saved_section,publish_saved_section). Edit it assection:<id>. Publishing one changes every page that uses it, so it needs Full; a page that uses a saved section that was never published cannot be published (SAVED_SECTION_UNPUBLISHED), and a saved section still used by any page, header, footer or slot cannot be deleted (SAVED_SECTION_IN_USE, listing every user). - Media: upload from a URL, change a media item's alt text, and delete it (30-day soft delete;
get_page_referencesshows what uses a page or media item first). - Custom widgets and code widgets (below).
The complete list of tools is in Tools, below.
Code widgets
A code widget is a custom widget whose markup, CSS and JavaScript run on the store page. Code can read and change anything on your store pages. So four things hold together:
- Off by default, per site, and only a person turns it on. In Throttle Builder, open Code and turn on Allow code widgets on this store (a workspace admin can; you confirm after reading the sentence above).
There is no MCP tool and no key that can do it. An agent that asks for code on a site where it is off gets
409 CODE_WIDGETS_OFF, and tells you to turn it on. - One click turns it all off. Turn off all code on the same screen takes effect on the very next request, even for a page your store cached: the script address then answers a script that does nothing.
- The key needs the code switch (granted by the workspace owner or the Builder's installer) to create, save, validate or roll back a code widget:
403 PERMISSION_REQUIREDwithrequired: "code"otherwise. - Never on checkout, cart, account or sign-in pages. The store's renderer has a route allow-list. It is not a setting and nothing changes it. A store's
BuilderProvidermust also cover its checkout and account layouts, so a visitor who leaves for one of those pages gets a full page load without any code. Details for store developers are in Rendering.
Every save is a version with its author (merchant:<id> or agent:<keyId>), shown on the Code screen with a Roll back button; list_code_widget_versions and rollback_code_widget do the same for an agent. A script is at most 64 KB and must parse (JS_SYNTAX names the line and column). Its function is called as run(root, input) once for each copy of the widget on the page, so a side effect on window should guard itself. The store loads the script from builder.usethrottle.dev, so a store with a strict Content-Security-Policy adds script-src https://builder.usethrottle.dev.
Credentials
| Who | Sends | Made on |
|---|---|---|
| Coding tools (Claude Code, Cursor, VS Code, Windsurf, scripts) | Authorization: Bearer tb_sk_..., a secret key. It is refused when the request carries an Origin, and a publishable key (tb_pk_...) never works here. | Keys and AI agents, in the Builder. |
| claude.ai and Claude desktop | An OAuth access token that Throttle issues after you sign in and approve. No key. | Settings, Connectors, Add custom connector: the address only. |
Both end up as one credential: an id (the key id or the grant id), its level and code switch, and the store it belongs to. Every write is recorded as agent:<id>.
OAuth for hosted assistants
An assistant that gets 401 from POST /mcp reads the WWW-Authenticate header, which points to https://builder.usethrottle.dev/.well-known/oauth-protected-resource/mcp (RFC 9728). That metadata names the Builder's own authorization server https://mcp.usethrottle.dev/builder (a client registers itself there by dynamic registration, so no client ID or secret is ever pasted) and these eight scopes:
builder:site:read, builder:site:write, builder:pages:read, builder:pages:write, builder:widgets:read, builder:widgets:write, builder:media:read and builder:media:write.
There is no publish scope. What a connection may publish is set by its level (see below), not by a scope.
Levels on the consent screen
A Builder connection carries a level and a separate code switch, chosen at consent. The level, not the scope list, is what limits the connection: the scopes of a read grant are the four :read scopes, and with a level chosen on the consent screen every other level holds all eight.
A Builder connection is for exactly one application, chosen on the consent screen; a request that lists several is refused with builder_single_application.
- Read: Reads your site and pages. Changes nothing.
- Draft: Edits drafts. Never publishes.
- Publish: Edits and publishes pages and site settings. Never publishes page deletions, saved sections or releases.
- Full: Publishes everything, including page deletions, saved sections and releases.
How high the person signing in may go depends on who they are in the workspace. The workspace owner, and the person who first installed the Builder (a later reinstall by anyone but the owner does not change this) while they still have Builder access, may grant any level and the code switch. Anyone else with Builder
access (a workspace admin, or an application admin or developer) may grant up to Publish, without code. Any other member may grant Read only. A request above that ceiling is 403 builder_level_not_allowed.
The consent screen reads the ceiling from GET /api/v1/oauth/builder-consent-options?workspaceId=&applicationId=&environmentId= (a signed-in dashboard session only), which answers { "data": { "maxLevel": "read" | "publish" | "full", "code": boolean } }, and sends the choice with POST /api/v1/oauth/authorize as builderLevel (read, draft, publish or full) and builderCode (boolean). Both apply to Throttle Builder clients only; any other client sending them gets 400 invalid_request. Leaving builderLevel out means read when every requested scope is a read scope and draft otherwise, and the grant keeps exactly the scopes requested. A connection made before levels existed has no level: GET /api/v1/oauth-grants/builder/:id/status answers builderLevel: null for it.
The Builder accepts a bearer token only when all of these hold; anything else is a refusal.
- RS256 only, verified against Throttle's keys (cached 10 minutes; an unknown key id refetches at most once every 30 seconds).
- The issuer is
throttle-oauthand the audience is exactly the MCP address above, and no other. - The lifetime is at most one hour, with 60 seconds of clock skew.
- The claims
grantId,workspaceId,applicationId,environmentIdandscopesare present, and at least one scope is abuilder:scope (else403 INSUFFICIENT_SCOPE). - The store has the Builder installed (else
403 BUILDER_NOT_INSTALLED). - The grant is still live. A revoked grant stops working within a minute.
503 AUTH_UNAVAILABLE with Retry-After: 5 and no WWW-Authenticate. The token may be fine:
retry, and do not send the user through sign-in again.
Releases over OAuth. A connection approved at the Full level has the release tools (list_releases, create_release, rollback_release), like a Full key.
At any other level they are not listed. A connection made before levels existed is treated as Publish (if its Allow publishing switch was on) or Draft, so it never lists them.
Drafts, and publishing when the level allows
Every edit tool saves to the draft; nothing is live until a publish. publish is listed only for a credential at the Publish or Full level, and the level is read live on every request:
lower it and the tool is gone at the next call. No tool and no API call can raise a level.
-
A credential that holds
publishpublishes on its own once the work is correct. The server's instructions tell it to runvalidate_pageand to look atdraftUrlin its own browser at 390, 768 and 1280 px first; it does not wait for you. A key withoutpublish(Read or Draft) stops there and hands you the preview link. -
publishneedsbaseRev, thedraftRevthe agent checked, so nothing it has not checked goes live (a changed draft isDRAFT_CONFLICT). WithincludeSiteit also needssiteBaseRev. A page with problems that would break the live store isPUBLISH_BLOCKEDwith each issue listed. - Full also publishes page deletions (a page deleted in the draft is not addressable by any tool, but
list_pagesshows it as a deletion waiting to be published), saved sections (publish_saved_section) and releases.create_releaseandrollback_releasechange the live store, so they need Full; they are available to a signed-in connection at that level as well as to a key. -
A widget a merchant turned off cannot be turned back on by an agent:
set_widget_statusanswersWIDGET_REENABLE_DASHBOARD_ONLY, which is not retryable. - A key made before levels keeps its own Allow publishing switch, off unless a merchant turned it on. See Levels.
1. get_site -> theme, locales, enabled packs, draftRev
2. list_widgets / list_data_sources -> what may be placed, with an example node each
3. create_page { title, slug } -> a draft, not live
4. add_section, add_widget, ... -> each answers { draftRev, issues }; pass draftRev back as baseRev
5. validate_page -> issues and publish warnings
6. get_preview_url { document } -> draftUrl and storePreviewUrl: open in your own browser at 390, 768, 1280
7. publish { document, baseRev } -> with the publish tool, once the work is correct
(no publish tool? stop and give the user the preview link) Scopes
A level is a fixed set of scopes (the table under Levels). The scopes are site:read, site:write, pages:read, pages:write, pages:publish, widgets:read, widgets:write, media:read, media:write, releases:read and releases:write. A tool is registered when the credential holds the scope it needs, and a :write scope also satisfies its :read. You choose a level, not scopes, when you make a key; only a key from before levels shows its scopes.
Conventions
- Documents are addressed as
part:header,part:footer,slot:<name>, a page slug or a document id fromlist_pages. - Writes answer
{ draftRev, issues }. Pass thedraftRevyou last read asbaseRev; a changed draft isDRAFT_CONFLICTand nothing is saved. - Every edit goes through the document operations (at most 500 per batch, atomic). An invalid batch answers
DOCUMENT_INVALIDwith its issues and the unchangeddraftRev. The operations are in the document schema. - idempotencyKey (optional, writes only): the same key and request within 24 hours replays the first answer. Keys are private to the credential and the tool. An insert tool needs
indexwhen it is given a key. - Money in data previews is
{ amount, currency, display }. Printdisplay. - Rate limits: 120 calls and 60 writes a minute per credential (
429withRetry-After). The allowance is counted per Cloudflare location, not globally. - create_page with a starting document is checked like a merchant's edit, and nothing is created if it fails.
- Errors are tool results with
isErrorand{ error: { code, message, ... } }.
{
"isError": true,
"content": [{ "type": "text", "text": "{ \"error\": { \"code\": \"DRAFT_CONFLICT\", \"message\": \"...\" } }" }]
} Tools
This list is generated from the server's tool catalog, so the scope of each tool is the one the server enforces; it is regenerated when the server's tools change. The tools an agent actually sees are the ones its level allows, so ask the connection (tools/list) when in doubt. A star marks a required input. Needs Allow publishing means a key from before levels must also have that switch on.
A destructive tool changes the live store or discards work, and a client may ask the user first.
Site settings
Theme, brand, menus, announcement, search and wording.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
get_siteread | site:read | source | Read the store's site settings (theme, brand, menus, announcement, seo, strings, routes, locales, storeUrl), its locales and which widget packs are enabled. Draft by default. The connections section answers { credentialSet } (whether a Throttle key is set), never the key. |
update_site_settingswrite | site:write | patch* baseRev idempotencyKey | Change one or more site sections (theme, brand, menus, announcement, seo, strings, locales, routes, storeUrl) in the draft. Each section you send replaces the whole section. Design lives in theme: preset ('clean', 'editorial', 'bold'); customized (true so your palettes apply instead of the preset's); light and dark palettes (14 colour tokens each: colorPrimary, colorPrimaryForeground, colorBackground, colorSurface, colorForeground, colorMuted, colorMutedForeground, colorBorder, colorBorderControl, colorAccent, colorSale, colorSuccess, colorWarning, colorDanger); fonts.heading, fonts.body and fonts.mono, each one of: Instrument Serif, Playfair Display, Lora, Merriweather, Cormorant Garamond, EB Garamond, Libre Baskerville, Source Serif 4, Fraunces, DM Serif Display, Inter, Schibsted Grotesk, DM Sans, Manrope, Poppins, Montserrat, Work Sans, Rubik, Nunito Sans, Open Sans, Lato, Raleway, Outfit, Plus Jakarta Sans, Figtree, Karla, DM Mono, JetBrains Mono, IBM Plex Mono, Space Mono, Bebas Neue, Oswald, Archivo Black, Space Grotesk, Syne, system-sans, system-serif, system-mono; radius (0 to 32 px); spacingScale ('compact', 'comfortable', 'roomy'); colorScheme ('light', 'dark', 'auto'); customCss (checked by the CSS sanitizer and scoped to the store's pages). Per-section layout, spacing and backgrounds are node settings (update_node). A bad value saves nothing and answers the issues. Nothing goes live until the site is published with publish. |
Widgets, data and links
What the assistant may place, what data it may bind, and what a link may point to.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
list_widgetsread | widgets:read | group | List every enabled widget with its settings (key, control, default, allowed values), its data inputs, where it may be placed and a minimal example node. Read this before add_widget. |
list_data_sourcesread | widgets:read | none | List the enabled data sources (products, a collection, categories, reviews, ...) with their params and the fields a widget may read. |
query_data_sourceread | widgets:read | source* params | Run a data source with params and answer a few sample results, for example to find a collection handle or see what a product grid would show. A collection, category or product param takes the handle from list_link_targets or the catalog id; an unknown handle answers NOT_FOUND (404). Prices are { amount, currency, display }; print display. |
list_link_targetsread | pages:read | query kinds limit | Search pages, collections, categories and products for a link. Each result has a target ({ kind, id }) ready to use in a link setting or a menu item. A page link is stored by the page id, so it follows the page when its slug or title changes. A page result has a state: 'published' (the store links to it) or 'draft' (the store shows the link as plain text until the page is published). |
Pages and drafts
Read, create and change pages and keep their versions.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
list_pagesread | pages:read | kind | List the site's pages, header and footer parts and slots with their state: draft changes, the published version and whether a deletion is waiting to be published. |
get_pageread | pages:read | document* published outline | Read a document, draft or published, with its node ids and draftRev. A draft with older widgets is upgraded first, so the draftRev you get is the one to write against. Use outline: true for a compact tree. |
create_pagewrite | pages:write | title* slug* pageType document idempotencyKey | Create a landing or content page (blank, or from a starting document) with a title and slug. It starts as a draft and is not live until published. |
create_slotwrite | pages:write | name* idempotencyKey | Create an empty slot document (a named area around the catalog's pages, such as product.below) so it can be edited with 'slot:<name>'. A slot is never deleted, only emptied. It is a draft until published. |
update_page_metawrite | pages:write | document* title slug pageType seo baseRev idempotencyKey | Change a page's title, slug, type or SEO in the draft. |
delete_pagewrite, destructive | pages:write | document* baseRev idempotencyKey | Delete a page in the draft (never the home page). A page that was never published is gone at once; a live page stays live until the merchant publishes the deletion in the Builder (this server cannot publish a deletion). The answer lists inboundReferences: every page, part, menu or announcement that links to the page, and a warning saying those links stop linking. Check them first and re-point or remove the links. |
validate_pageread | pages:read | document* | Check the draft: structural issues and publish warnings (a missing image, an empty link, a missing collection, a link to a page that was deleted or is not published: PAGE_LINK_DELETED, PAGE_LINK_UNPUBLISHED). |
get_preview_urlread | pages:read | document* version | Get the links to check your work in your own browser tool: draftUrl (the draft, read-only, no sign-in, valid 12 hours, drawn at the window's own width so open it at 390, 768 and 1280), liveUrl (the published page on the store, or null), storePreviewUrl (the draft on the store itself, the only place code widgets run) and the widths. |
discard_draftwrite, destructive | pages:write | document* idempotencyKey | Reset a draft to its published copy, dropping unpublished changes. |
list_versionsread | pages:write | document* version | List a document's saved versions, or read one in full. |
restore_versionwrite | pages:write | document* version* baseRev idempotencyKey | Load a saved version into the draft. The current draft is checkpointed first; nothing is published. |
list_changesread | pages:read | document* limit | List the newest draft changes of a document (or of the site settings with document 'site'), newest first: seq, who made it, a summary, when, and whether it was undone. undoable marks the one change undo_change would undo now. Needs site:read for 'site'. Edits to a draft (and discard_draft and page title, address and SEO changes) are listed; restoring a version, deleting a page and the upgrade on open are not (a restore keeps its own checkpoint, see list_versions), and undo cannot step back past them. |
undo_changewrite | pages:write | document* seq* idempotencyKey | Undo one change, by its seq from list_changes (document 'site' for the site settings; needs site:write). Only the change marked undoable works: the newest that is neither an undo nor already undone. Call again to walk further back. Anything else is refused with DRAFT_CONFLICT, and so is an undo that would step back past something the journal did not record (a version restore, a page deletion, the upgrade done when a page with older widgets is opened). An undo is itself a change in the list but cannot be undone: make the edit again instead. Edits the draft only; nothing is published. |
create_saved_sectionwrite | pages:write | title* fromNodeId section idempotencyKey | Save a section as a saved section: build it once, put it on many pages by reference (insert_saved_section), and edit it once to change every page that uses it. Give fromNodeId (a top-level section already in a document) or section (a section node). It starts as a draft and is never shown on a store until it is published (publish_saved_section, Full level). Answers its id; edit it with the node tools and document 'section:<id>'. |
list_saved_sectionsread | pages:read | none | List the saved sections with their published version, whether the draft has changes not yet published and the pages, parts and slots that use each (usedBy). Read one with get_page and document 'section:<id>'. |
insert_saved_sectionwrite | pages:write | document* savedSectionId* index* baseRev idempotencyKey | Put a saved section on a page, header, footer or slot by reference, at a section index. The document shows the saved section's published content; changing the saved section later changes every document that uses it. A page that uses a saved section cannot be published until the saved section is published (PUBLISH_BLOCKED, SAVED_SECTION_UNPUBLISHED). |
detach_saved_sectionwrite | pages:write | document* nodeId* baseRev idempotencyKey | Replace a saved-section reference in a document with an ordinary copy of the saved section's PUBLISHED content (new ids), so this document can differ from it. Other documents keep using the saved section. Answers the new section id. |
delete_saved_sectionwrite, destructive | pages:write | savedSectionId* idempotencyKey | Permanently delete a saved section that no page, header, footer or slot uses (draft or published). Refused with SAVED_SECTION_IN_USE and the list of documents that use it (usedBy): detach or remove those first. Destructive and not undoable: ask the user first. |
get_page_referencesread | pages:read | document* | Which documents and site settings link to or embed a page (draft and published counts), so you know what a rename, deletion or unpublish would affect. |
Editing a page
Small edits, and one atomic batch for bigger builds.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
add_sectionwrite | pages:write | document* index columns widths props baseRev idempotencyKey | Insert a section with N columns and widths at an index. Answers the new section and column ids. |
set_columnswrite | pages:write | document* sectionId* widths* device moveChildrenTo baseRev idempotencyKey | Change the column count and widths of a section, for desktop, or only the widths for tablet or phone. |
add_widgetwrite | pages:write | document* parentId* type* index props data baseRev idempotencyKey | Insert a widget into a column (or inner column) with its settings and data bindings. Answers the new widget id. Read list_widgets for the settings first. |
add_inner_sectionwrite | pages:write | document* parentId* index columns widths baseRev idempotencyKey | Insert an inner section (columns inside a column) into a top-level column. |
update_nodewrite | pages:write | document* id* props* baseRev idempotencyKey | Set settings on a section, column or widget (setProps). |
set_responsivewrite | pages:write | document* id* device* props* baseRev idempotencyKey | Set or clear tablet or phone overrides on a node. |
set_data_bindingwrite | pages:write | document* id* name* binding* baseRev idempotencyKey | Bind a widget input to a data source, or remove the binding. |
move_nodewrite | pages:write | document* id* parentId* index* baseRev idempotencyKey | Move a node to another parent or position. |
duplicate_nodewrite | pages:write | document* id* baseRev idempotencyKey | Copy a node (with everything in it) right after the original. Answers the copy id. |
remove_nodewrite | pages:write | document* id* baseRev idempotencyKey | Remove a node and everything in it. |
apply_opswrite | pages:write | document* ops* baseRev idempotencyKey | Apply a batch of document operations atomically, for bigger builds. If any operation is invalid nothing is saved and the answer lists the issues. |
Media
The store media library.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
list_mediaread | media:read | query limit cursor | List the store's media library. |
upload_media_from_urlwrite | media:write | url* alt idempotencyKey | Add an image to the media library from a public https URL. Answers the asset id to use in image settings. |
update_mediawrite | media:write | id* alt* idempotencyKey | Change the alt text of a media asset in the library. It changes the library entry only: it does not change any page and nothing goes live. A page image's alt text is the image widget's own alt setting, so set it with update_node on that widget. Catalog data (products, collections, categories) is read-only here. |
delete_mediawrite, destructive, needs Allow publishing | media:write | id* idempotencyKey | Delete a media asset from the library. Throttle keeps a deleted file for 30 days, so published pages keep showing the image until then and show a broken image after that. Check where it is used first (get_page_references lists what links to a page; look through get_page on the pages that show the image). Destructive: ask the user first. |
Custom widgets
The same checks as the Widget API.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
create_widgetwrite | widgets:write | definition* idempotencyKey mode | Store a custom widget definition (a new widget, or its next version). Use validate_widget first. |
validate_widgetread | widgets:write | definition* | Check a custom widget definition without storing it. Answers its issues. |
set_widget_statuswrite, destructive | widgets:write | type* version status* idempotencyKey | Turn a custom widget off or on. A widget a merchant turned off can only be turned back on by the merchant, in the Builder: this tool answers WIDGET_REENABLE_DASHBOARD_ONLY for it, and you should tell the user instead of retrying. |
delete_widgetwrite, destructive | widgets:write | type* idempotencyKey | Permanently delete a custom widget type and all its versions. Destructive and not undoable: ask the user first. The type must already be turned off (set_widget_status) and no page may use it (WIDGET_NOT_DISABLED, WIDGET_IN_USE). A widget a merchant turned off can only be deleted by the merchant, in the Builder. |
create_code_widgetwrite | widgets:write | definition* idempotencyKey | Create a code widget: markup and CSS plus a script that runs on the store page (not in the Builder editor, which only draws it). Needs the Code switch on the key, and the store owner must have turned code widgets on in Throttle Builder (CODE_WIDGETS_OFF otherwise: tell the user, do not retry). Code can read and change anything on your store pages. It never runs on checkout, cart, account or sign-in pages. To check it, open storePreviewUrl from get_preview_url in your browser. |
update_code_widgetwrite | widgets:write | definition* idempotencyKey | Save the next version of an existing code widget. Needs the Code switch and code widgets turned on for the store. Every save is a version with your key as its author; roll back with rollback_code_widget. |
validate_code_widgetread | widgets:write | definition* | Check a code widget definition without storing it: markup and CSS rules and the script syntax (JS_SYNTAX with line and column). Needs the Code switch and code widgets turned on for the store. |
list_code_widget_versionsread | widgets:read | type* | List the versions of a code widget with who saved each and when. Read-only. |
rollback_code_widgetwrite | widgets:write | type* toVersion* idempotencyKey | Bring an earlier version's code back as a new version. Needs the Code switch and code widgets turned on for the store. |
Publishing
The tools that put work on the live store: pages and site settings, and saved sections.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
publishwrite, destructive, needs Allow publishing | pages:publish | document* baseRev* includeSite siteBaseRev idempotencyKey | Publish a document, and optionally the site settings, so it goes live. baseRev (the draftRev you checked) is required, so nothing you have not checked is published. Answers the published version. Check the work first: validate_page, then open the draftUrl from get_preview_url in your own browser tool at 390, 768 and 1280 px wide. Publish once the work is correct. Only available when the merchant allowed this credential to publish. |
publish_saved_sectionwrite, destructive | pages:publish | savedSectionId* baseRev* idempotencyKey | Publish a saved section, so every published page, header, footer and slot that uses it shows the new content. It changes many pages at once, so it needs the Full level. baseRev (the saved section's draftRev you checked) is required. Check the work first: validate_page, then open the draftUrl from get_preview_url in your own browser tool at 390, 768 and 1280 px wide. |
Releases (build-time stores)
For stores that read a frozen release. See the delivery modes page.
| Tool | Scope | Inputs | What the model reads |
|---|---|---|---|
create_releasewrite, destructive, needs Allow publishing | releases:write | idempotencyKey | Build-time stores only: freeze everything published right now into a release and call the store's deploy hook once. A release changes the live store, so it needs the Full level (a key from before levels: the releases:write scope AND the merchant's Allow publishing). Answers the release and its deploy status. |
list_releasesread | releases:write | limit before | Build-time stores only: list releases, newest first, with their deploy status. Needs the releases:write scope. |
rollback_releasewrite, destructive, needs Allow publishing | releases:write | releaseId* idempotencyKey | Build-time stores only: make a new release that re-deploys an earlier release. It changes the live store, so it needs the Full level (a key from before levels: the releases:write scope AND the merchant's Allow publishing). |
Troubleshooting
| What you see | Why | What to do |
|---|---|---|
| 401 or "Authentication failed" | The key was revoked, was mistyped or cut short when copied, or the header is not exactly Authorization: Bearer tb_sk_... (the word Bearer, one space, then the key). Keys do not expire. | Use Test connection with the key, on the Connect an AI agent screen. If it fails, make a new key (a key is shown once), put it in your tool and revoke the old one. A signed-in assistant that gets 401 was revoked or timed out: connect it again. |
403 PERMISSION_REQUIRED | The key or connection has a level too low for that call. The answer names what is missing (level:publish, level:full or code), and a tool the level does not allow is not even listed. | Raise its level in Keys and AI agents. It applies on the very next call. Only the workspace owner or the person who installed Throttle Builder can grant Full and code. |
| 429, rate limited | More than 120 calls, or 60 changes, in a minute on one key. | Wait a few seconds (the answer says how long) and ask again. Ask the agent to do fewer, larger edits. |
| The agent has no publish tool | The key or connection is at Read or Draft. Only Publish and Full can publish; a key from before levels also needs Allow publishing. | Raise its level to Publish, or publish yourself in the Builder. |
PUBLISH_BLOCKED | The page has problems that would break the live store. The answer lists each issue. | Ask the agent to fix the issues listed, preview again, then publish. |
DRAFT_CONFLICT | The draft changed after the agent read it (you or another agent edited it). | Ask the agent to read the page again and redo its edit on top of the new draft. |
SAVED_SECTION_UNPUBLISHED | The page uses a saved section that has never been published, so the live store would have nothing to show. | Publish the saved section first (this needs Full), then publish the page. |
| A page deletion, saved section or release is refused | Publish never publishes page deletions, saved sections or releases. Only Full does. | Raise the level to Full (owner or installer), or publish that deletion yourself in the Builder. |
409 CODE_WIDGETS_OFF | Code widgets are off for this store. Only a person can turn them on. | Turn them on in Throttle Builder under Code if you want them (read the risk first), or ask the agent for a widget that needs no code. |
| A page with a saved section, or a tabs section, looks wrong on the store | The store runs builder-react or builder-schema older than 0.4.0 / 0.2.1. | Upgrade the store. See Versions on the Throttle Builder page. |
| VS Code on macOS gets 401 with THROTTLE_BUILDER_KEY set | VS Code opened from the Dock does not see variables exported in your shell, so ${THROTTLE_BUILDER_KEY} in .mcp.json is empty. | Start VS Code from a terminal where the variable is set (code .), or set the variable for GUI apps, then restart VS Code. |
| claude.ai says it "couldn't connect" | A new connection can take up to 5 minutes to be recognised, or the sign-in was cancelled part way. claude.ai cannot send a key: it signs in to Throttle. | Wait 5 minutes after setup and reconnect. Paste the address only, leave Advanced settings empty, and approve on the Throttle page. If it still fails, remove the connector, add it again, and check that Throttle Builder is installed on the application you chose. |
The keys and the connection are explained for merchants in the setup guide.