ae-setup

Getting After Effects connected

The tools talk to a small panel that runs inside After Effects. Three things must be true for that to work: the panel is installed, Adobe is willing to load it, and AE is open.

Assume the person you are helping is a motion designer, not a developer. They should never need to open a terminal — you have tools for all of this.

Always start with check_setup

check_setup is read-only and safe to call at any time. It returns a checks array and a nextSteps list already written in plain language.

Relay nextSteps to the user directly. Do not paraphrase it into jargon, and do not invent steps it did not mention.

A timeout is not a disconnection

Before you start any repair, work out which of five failures you have. They read alike and their remedies contradict each other:

• Did not answer in time — something is listening; it is just too busy to reply. After Effects is single-threaded, so a long script or a modal dialog waiting for a click blocks it completely. Nothing is broken and nothing needs installing. The call did reach After Effects and may still be running, so do not re-send it.
• Cannot reach — nothing is listening on the port the server tried. That is the case the repair path below is for — unless the next case applies, so read the message to the end: it now says which other ports it looked at and what it found there.
• Cannot reach on port X, while check_setup reports the panel on port Y — the server's idea of the port went stale, not the panel. The panel is running and answering; the server was started from a port file that no longer described it. check_setup reports this as its own check, portAgreement, with both numbers. Retry the failed call: the server re-checks the port whenever a call is refused and switches to the port that answers by itself. If it still fails, reconnect the MCP server (restart the client's connection to it, not After Effects). Never restart After Effects for this — something is listening, and a restart costs the user their work in progress for nothing.
• Refused: the bridge token did not match — the panel is running and answered straight away, and what it answered was no. The call never reached After Effects, so nothing in the project changed. The bridge requires a token because it is an HTTP server on 127.0.0.1 and a web page in the user's browser can reach that; the panel writes one beside its port file each time it binds. Do not restart After Effects, do not run setup_panel, and do not re-send the call — it will be refused identically until the cause is fixed. Run check_setup: its bridgeToken check says whether the token file is readable, and nextSteps carries the rest. The usual causes are an MCP server older than the running panel (update it and reconnect) or a server that cannot see the file the panel wrote, which happens when the client runs it sandboxed or as another user.
• Waited behind another op for the write queue and was dropped — the panel is fine and this call never left the server, so nothing in the project was changed. Writes are serialized so that they land in the order the agent issued them and nothing drops into the middle of work the user asked for as one thing; something in front is taking a very long time, usually a long run_batch. Re-sending is safe here, once the work in front has finished; this is the one of the four where it is. Find out what is in front with get_job or await_job — reads are never queued, so list_ and get_ calls still answer.