Troubleshooting

The Synthetic Illustrator MCP panel says "Disconnected"

Symptom: The panel inside Illustrator never connects to the server, or tools error out with a connection failure.

Fix: Confirm the MCP server is actually running (your MCP client launches it on startup). The panel retries the connection every 3 seconds on its own — no need to reopen it. If it still won't connect, restart Illustrator entirely (the panel doesn't always reload cleanly after a network or port change).

MCP client says illustrator-mcp didn't respond

Symptom: The client loads the server but then times out or says 'tool not available'.

Fix: Confirm Illustrator is open with a document loaded, and that the Synthetic Illustrator MCP panel says "Connected". The server talks to Illustrator through the bridge plugin over WebSocket — without the app, a document, or the panel connected, tools error out. Then restart the MCP client.

Invalid license error

Symptom: Client logs say 'license validation failed' or 'IL_MCP_LICENSE not set'.

Fix: The license in your config doesn't match the one on /dashboard/licenses. Recopy it — check for leading/trailing spaces when you pasted it into the JSON.

The CEP panel doesn't show up in Illustrator

Symptom: You installed the bridge panel but don't see Synthetic Illustrator MCP under Window → Extensions (Legacy).

Fix: Fully restart Illustrator after installing (closing and reopening the panel isn't enough). If you installed it manually, make sure the .zxp installation finished, or just run the Synthetic installer again — it detects and repairs the panel. Open a support ticket if it still doesn't appear.

npx is slow on every launch

Symptom: Every time the MCP client starts, it takes 10-30s to load the server.

Fix: npx checks for an update on each launch. To make it instant, install it globally: npm i -g @synthetic-ai/illustrator-mcp then change command in the config to illustrator-mcp (no npx, no args).