What AI apps can do

Syntope MCP gives an AI app six tools. You do not call them yourself. Ask in plain words, such as “Change color.primary to #0066FF in the base set”, and the app picks the tool. Setup is in Connect your AI app.

Partial: import works only in an empty project, and applying uses the default option of every theme group.

Tool	What it does	Access it needs	How to take it back
syntope_list_tokens	Reads saved tokens	read tokens	Changes nothing
syntope_read_layers	Reads Figma layers	read tokens	Changes nothing
syntope_change_tokens	Sets, deletes or renames saved tokens	read and change tokens	syntope_undo_change, or Undo in Figma
syntope_import_tokens	Imports a whole project into an empty one	read and change tokens	syntope_undo_change, or Undo in Figma
syntope_apply_tokens	Applies saved tokens to layers	read and change tokens	⌘Z in Figma
syntope_undo_change	Takes back the app’s own token change	read and change tokens	Not applicable

What the tools work on

Saved tokens. The tools read and write saved Syntope tokens. Unsaved drafts in the plugin are not visible to them.

Not Figma variables. No tool reads Figma variables. A layer read names the properties a variable sets on a layer, and nothing else about the variable. To map tokens to variables, use the plugin: see Figma variables.

The plugin must be open. Every request goes through Syntope Tokens, open in the file in Figma Desktop. If it is closed, the request fails. A mode of Syntope MCP that works on token files without Figma is planned, not built. To work on token files without Figma today, use Syntope Engine in code.

One file at a time. The tools use the file you last worked in where the plugin is open. Each read names that file. If you switch files between a read and a write, the write is refused and nothing is sent to the new file. No other allowed file is used instead.

The plugin and Syntope MCP talk over a local connection. Results go to the AI app you allowed, and what it does with them is up to that app. Git credentials are not sent over this connection.

Permission and approval

You set the access per app and per file: read tokens or read and change tokens. If an app asks for more than it has, the plugin in that file asks you at once. Details are in Connect your AI app.

With read and change tokens, the app does not ask you before each change. To be asked first, use your AI app’s own tool permissions, or keep the app on read tokens.

Each token change shows a Figma notification with Undo for 10 seconds. It is also listed under changes in this document on the app’s card in Settings → MCP, where the latest change has undo.

Each write names the revision the app last read. If the tokens changed since then, the write is refused with revision_conflict and nothing is saved.

syntope_list_tokens

Reads the tokens in your saved sets. It can filter by text in the token path, by exact type, or by set location or folder. It returns 100 tokens by default and up to 500 per page. The app reads on page by page.

• Each token appears once per set that defines it.
• Values and references are as written, not resolved for a theme. To see a resolved value, open the set in the plugin.
• Empty sets and theme groups are not listed. To see them, check the set list and the Themes tab in the plugin.
• If references are broken, every page lists them for the whole project.

syntope_read_layers

Reads the current selection, up to 500 layers by ID, or the layers whose name contains a text. By default it goes 3 levels below each layer.

For each layer it returns the ID, name, type, parent and depth. When they exist, it also returns variant values, the start of a text layer’s text, the Syntope tokens already linked, the properties a Figma variable sets, current values as text, and the properties that can take a token.

Large reads come in parts. If the layers change between parts, the app has to read from the start.

syntope_change_tokens

Makes up to 500 operations in one call, saved together or not at all.

Operation	Effect
set	Creates a token or replaces the saved token whole. Fields left out are removed
delete	Removes the token
rename	Moves the token to another path in the same set

set creates a missing set and adds it last in Base. delete and rename need an existing set. Values follow each token type.

{
  "baseRevision": "<revision from the last read>",
  "changes": [
    {
      "op": "set",
      "set": "brand/color",
      "path": "color.primary",
      "token": {
        "$type": "color",
        "$value": { "colorSpace": "srgb", "components": [0, 0.4, 1] }
      }
    },
    { "op": "rename", "set": "brand/color", "path": "color.accent", "to": "color.highlight" },
    { "op": "delete", "set": "brand/color", "path": "color.old" }
  ]
}

The whole call is refused in these cases:

• A delete or rename targets a token that others reference. The result names them. Change or remove those references first.
• Creating a set would change how Base is worked out in an older project. Add the set in the plugin, then retry.

syntope_import_tokens

Every import replaces all token sets and themes, so this tool works only in an empty project. An empty saved set or a theme group, even a switched-off one, counts as content.

It takes one DTCG Format file, a DTCG Resolver package with every file it references, or a Tokens Studio export. The app sends the file contents. Syntope MCP reads no local files.

• To add to a project that has tokens, ask the app to add them. It uses syntope_change_tokens.
• To replace a project, use the import tokens dialog in the plugin, which shows what it replaces. See Import and export.
• A Resolver package needs one Resolver set, first in resolutionOrder as Base, then each theme group once with a default. Files that need automatic Base conversion go through the import tokens dialog too.
• A Tokens Studio export is converted as in the import tokens dialog. The result gives counts and the first 20 notes. To see every note, import the file in the dialog.

syntope_apply_tokens

Applies saved tokens to layers, with the same writes as the Apply menu in the plugin. Each item names a token by set and path, and one layer property. The layers come from the item, from the call or, without either, from the current selection.

The value applied is the one under the default option of every theme group. The layer is linked to the token, so Inspect and Sync know it. If a token’s set is not used by those default options, the layer is skipped: apply a token from a set they use, or change the default theme option.

This can change many layers in one call. Syntope MCP tells AI apps to show you the plan before more than a few layers change. Whether it does is up to the app.

• The property must fit the token’s type and the layer. See Apply targets.
• A property set by a Figma variable is skipped, not replaced. To replace it, apply the token in the plugin, which asks first.
• A layer property takes one token. Two on the same one refuse the call.

The result lists what changed and what was skipped, with a reason for each. Troubleshooting explains the reasons.

To undo, press ⌘Z once in Figma. That takes back the whole call. syntope_undo_change does not undo an apply.

syntope_undo_change

Takes back a token change or import made by this app, newest first.

• A later change has to be undone first, whether an AI app or you made it in the plugin. Undo that one, then try again.
• If the tokens were changed outside this history, for example from another window, undo is refused. Restore the earlier state with a new change.
• An app cannot undo another app’s change. Choose undo on that change in Settings → MCP.
• A change that was already undone cannot be undone again.

The history holds the last 50 changes and lasts only while the plugin stays open. After you close it, restore earlier tokens from your Git repository: see Sync.

Limits

Limit	Value	If you reach it
Tokens per page	100 by default, 500 at most	The app reads on page by page
Operations per syntope_change_tokens call	500	Split into several calls. Each call saves on its own
Size of one change	8 MiB	Split into smaller requests
Layer IDs per list	500	Use several calls
Items per syntope_apply_tokens call	500	Use several calls. Each is its own ⌘Z step
Layer and token pairs per apply	1,000	Apply fewer tokens per call, or select fewer layers
One layer read	1,000 layers or about 30,000 characters	The app reads on in parts
Levels below a layer	32	Read the deeper layer by its ID
Requests waiting per AI app	32	Wait until they finish
Time per request	Read 30 seconds, write 55 seconds	Keep the plugin open and ask again. After a lost write, read first
Undo history	50 changes, while the plugin stays open	Restore from your Git repository