Read theme variables and stylesets with the ConvertSite MCP

The Read tool in the ConvertSite MCP, shown to your assistant as Read app content, can return an app's complete design system through two read-only resources: theme for the app's theme variables, workspace fonts, and breakpoints, and stylesets for the app's reusable component styles. Both are part of the standard MCP connection with no extra setup or permission, so you can ask your assistant to inspect what already exists before it restyles anything. This article is a field reference for what those two reads return and the errors they produce.

What you need

Connect Claude or Codex to ConvertSite first. The reads are read-only, so the read scope the standard connection grants (convert:apps.read) is all they need; write access is not required. New to the connection? See Connect ConvertSite MCP to Claude or Connect ConvertSite MCP to Codex.

Read the theme

Call the Read tool with resource: "theme". The response returns the app's variables, workspace_fonts, and breakpoints. Every theme variable in the app appears in variables, each with these fields:

Layers and overrides

A theme variable can be defined at three layers: the built-in default, the workspace, and the app. The source field tells you which layer is winning. When a lower layer is shadowed, the variable also returns an overrides array listing each hidden lower-layer value with its source (default or workspace). When nothing is shadowed, the field is omitted.

Color spectrum variables

A color spectrum variable additionally returns a shades map of shade numbers to color values, and its css becomes var(<theme-key>-<shade>) so your assistant can reference individual shades. The value field for a spectrum is its base color.

Usage counts

used_by.components counts the components whose inline styles reference the variable, and used_by.stylesets counts the stylesets whose styles reference it. Each component or styleset counts once no matter how many times it references the variable, and a reference to a color-spectrum shade counts toward the spectrum variable. The counts include components inside blocks, not only page content, so a high count means changing the variable reaches everywhere it is used.

Workspace fonts

Each entry in workspace_fonts describes one font family with these fields:

• family: the font family name.

• weights: the weights available in the library.

• styles: the styles derived from the font faces.

• variable: whether any face is a variable font.

• sources: contains upload when the family has uploaded faces and embed when it has embedded faces.

Breakpoints

The response always includes exactly three breakpoints:

The same suffixes appear in styleset style keys (see below), so a @tablet value means the tablet breakpoint.

List component stylesets

Call the Read tool with resource: "stylesets" and no filters to get every effective styleset in the app. Each variant returns:

origin is exactly one of builtin (the built-in styleset is unchanged), builtin_modified (a built-in styleset has been customized), or custom (it is not a built-in styleset). scope is exactly one of builtin, workspace, or app.

The styleset-level overrides array lists the lower layers that styleset hides, for example a stored styleset shadowing a workspace or built-in definition with the same key. used_by_components counts the components using the styleset, including components inside blocks. Without filters, the response lists these summary fields only; detailed styles require a filtered read.

To create, apply, or edit stylesets yourself in the editor rather than through your assistant, see Component stylesets.

Narrow a styleset read

Two optional filters focus a stylesets read: identifier takes a component tag, for example button, and returns the variants for that component kind, while selector takes an exact styleset key and returns that one styleset and its inline overrides. You can combine both filters to read a specific styleset of a specific component kind.

When either filter is supplied, each returned styleset also includes an elements map keyed in the form element:[email protected], with the style value as a string exactly as stored, including CSS values and var(...) theme-variable references. A key such as button:[email protected] means the background color of the button's Hover state at the tablet breakpoint. Desktop values carry no breakpoint suffix, tablet keys use @tablet, and mobile keys use @mobile.

A selector read additionally returns components_with_overrides: the components that use that styleset and also override it inline. Each entry carries the component's id, its styles, and a page field for page components or a block_id for components inside blocks. Components that use the styleset with no inline overrides are left out. The list is capped at 50 returned components, and a total field reports the full number collected.

What your assistant sees for an unknown identifier

A filtered read fails with a message your assistant can read and correct itself, so a wrong value costs one retry, not a support ticket. Two cases exist:

Example: restyle with the existing variables

Before restyling an app, ask your connected assistant to read the design system first, for example: "Read the theme and the stylesets for button, then tell me which theme variables the current button styles use." The response shows every variable, which layer defines it, and how many components and stylesets depend on it, so your assistant can build new styles on the existing var(...) references instead of hard-coding color and spacing values. Change a variable once in the editor and every component connected to it updates; see Style variables for how variables work in the editor.

These two reads change nothing: they only report what is already in the app. For how the layers they report fit together in the editor, see How styling works in ConvertSite.