Find what you see below. AI apps usually pass on the message, and sometimes a code, shown here in backticks. “Syntope Tokens on this Mac” means Syntope MCP. “Syntope Tokens in Figma” means the plugin.
First checks
The plugin is open in the right file, in Figma Desktop, and stays open.
The plugin and Syntope MCP come from the same release.
Ask your AI app: “Show me my Syntope tokens.” This starts Syntope MCP if it is not running. The plugin cannot start it.
Install Codex, Claude Code or Cursor, then open the installer again. For Claude Desktop, use the .mcpb. The installer looks for Codex and Cursor in /Applications and ~/Applications, and for the codex and claude commands in ~/.local/bin, /usr/local/bin and /opt/homebrew/bin. It does not see folders added only in your shell settings, so install the command in one of those
“An AI app changed its settings while Syntope Tokens was installing.”
Quit Codex, Claude Code and Cursor, then open the installer again
“Syntope Tokens could not read app’s settings.” or “app already has a different Syntope Tokens setup.”
Nothing was changed. Window → Installer Log → Show All Logs names the file. Fix its syntax, or rename the other server called syntope in the app’s settings, then open the installer again
“Program is using the connection Syntope Tokens needs.”
Quit that program, then open the installer again
“Syntope Tokens is already installing.”
Wait for it to finish, then open the installer again
“Open the Syntope installer from your own Mac login, without sudo.”
Log in as yourself and open it from Finder
“Syntope Tokens could not be set up”
Email support and attach the log from Window → Installer Log
Your AI app does not see Syntope Tokens
What you see
What to do
No Syntope Tokens tools in the app
Check that it is on: Codex in its MCP settings, Claude Code with /mcp, Cursor in Settings → Tools & MCP, Claude Desktop in Settings → Extensions. Not listed? Quit the app, install again, reopen it. A project or managed configuration can override your own settings
Claude Desktop shows the extension as failed
Read its status and logs in Claude’s Extensions or Developer settings. Use the file for your Mac’s chip
“This AI app is not set up for Syntope Tokens on this Mac.” (client_unregistered, client_authentication_failed, bridge_configuration, registry_configuration)
Install again from the release page, then reopen the app
“Syntope Tokens is closing in this AI app.” (app_closing)
Restart the AI app
Connecting in Figma
What you see in the plugin
What to do
“Open your AI app and ask it to read your Syntope tokens. Waiting for it to connect…”
Normal while Syntope MCP is not running. Ask your AI app. The plugin connects by itself
No number appears
Ask your AI app first. The Mac window opens only after an app has asked. Then choose connect
The numbers differ, or no Mac window appears
Do not approve. Choose cancel connection, then connect for a new check
“The connection check ran out of time.” or “The approval expired. Choose Connect to try again.”
You have 2 minutes. Choose connect
“This approval took too long and ended.”
Choose allow file access again
“The connection was not approved.”
Choose connect when you are ready
“Another connection check is already open on this Mac, or too many were started.”
Finish or close the other check. Only one Mac window can be open, and five checks can start per hour. If you hit that limit, wait, then choose connect
“Syntope Tokens on this Mac changed since this file was connected”
Choose connect again, compare the numbers and allow your apps again. Earlier file access does not carry over
“This file was approved in another Figma app on this Mac, such as Figma in the browser.”
Open the file in the Figma app where you approved it
“Open a saved Figma file before connecting.”
Save the file in Figma, then choose connect
“This file changed, so the connection ended.”
Choose connect in the file you want to use
“Syntope Tokens on this Mac is older than Syntope Tokens in Figma.”
Quit your AI apps, choose download Syntope Tokens for Mac and install it. The plugin connects again by itself
“Syntope Tokens on this Mac is newer than Syntope Tokens in Figma.”
Update the plugin from the same release, then open it again
“Syntope Tokens on this Mac couldn’t save your change.” (save_failed)
Choose connect to see whether it was saved, then make the change again if needed
Other messages that end with “Choose Connect”
Choose connect
The MCP icon in the plugin footer shows the state when you hover over it:
Icon says “AI connection: …”
What to do
“no AI app allowed” or “choose an app to allow file access”
Choose allow file access in Settings → MCP
“AI app not open”
Open your AI app and ask again
“AI app uses another document”
Click in this file in Figma. Apps follow the file you last worked in
“connection error”
Open Settings → MCP and read the message there
“not connected”
Ask your AI app. If the plugin stays offline, choose connect
The AI app cannot use the file
Code
What to do
syntope_not_open
Open the plugin in the file you want and keep it open
file_closed
The plugin is closed in the file you used last. Open it there, or click in another file where it is open. No other file is used instead
file_ambiguous
The plugin is open twice for this file, for example in the Figma app and a browser. Close one
file_reconnecting
Try again in a few seconds
file_changed
You switched files. Nothing was changed. Ask again so the app reads first
Nothing was saved. Ask again so the app reads the current tokens first
editor_busy
Finish the open dialog, unsaved JSON draft, running save, or provider or variables operation in the plugin, or wait until the tokens load. Then try again
change_rejected
Nothing was saved. errors names each problem and the operation that caused it. dependency-blocked lists the tokens that reference the target: change those first. automatic-base-conversion means you add the set in the plugin first
import_rejected
Nothing was saved. With project-not-empty, ask the app to add specific tokens, or use the import tokens dialog. automatic-base-conversion also needs that dialog. Otherwise fix the errors diagnostics names
not_undoable
A later change comes first, the tokens changed outside the history, or the change belongs to another app
frame_too_large
Split the change into smaller requests
unknown
The result was lost and the change may be saved. Ask the app to read the tokens before it retries. A retry with the old revision cannot apply twice
write_result_too_large
The change may be saved. Ask the app to read the tokens, then send smaller changes
Use a set and path that syntope_list_tokens returns
property_not_supported
Use a property the token’s type supports. The message lists them
same_property_twice
Choose one token per layer property
no_selection
Select the layers in Figma, or pass their IDs
too_many_layers
Apply to at most 1,000 layer and token pairs per call
tokens_changed
The tokens changed behind the plugin, for example with Figma undo. Ask the app to read them again
If the answer is lost, some layers may have changed. For apply_unknown, apply_unavailable and apply_result_too_large, check the layers in Figma. ⌘Z undoes the apply. syntope_undo_change does not.
One call can apply to some layers and skip others. Each skipped layer has a reason:
Reason
What to do
layer_not_found
Check the layer ID, or select the layer
variable_bound
A Figma variable sets this property. Apply the token in the plugin, which asks before replacing it
property_not_on_layer
Choose a property syntope_read_layers lists for this layer
shadow_spread_not_on_layer
Choose a shadow token without spread, or turn on Clip content and give the layer a fill
font_unavailable
Install or replace the font in Figma, then apply again
broken_reference
Fix the reference. syntope_list_tokens lists broken references
token_has_no_value
Fix the token in the plugin, then apply again
not_in_default_theme
Apply a token from a set the default theme options use, or change the default option
check_layer
The property may have changed only partly. Check the layer. ⌘Z undoes the apply
A changed layer with the note not_linked has the new value, but no link to the token. Inspect and Sync do not show or update it. Apply the token to that layer again.
Syntope MCP on your Mac
Code
What to do
bridge_in_use
Another program holds the port Syntope MCP needs (41414). Quit the program the message names. If it says another version of Syntope Tokens is running, open the installer again, or quit and reopen Claude Desktop
broker_incompatible
Install the latest version from the release page, then reopen the app
broker_disconnected, bridge_closed
Ask again. It reconnects by itself and your approvals stay. Keep the plugin open
registry_closed
Syntope MCP is shutting down. Ask again and it starts by itself
platform_unsupported
Run Syntope MCP on a Mac. Windows is not supported
--diagnose checks the installed files and reports their versions. It does not query a running Syntope MCP, which can stay on an older version until the last AI app quits.
