Security

Security

Surehand MCP gives an AI app the power to run scripts in After Effects. This page explains what protects you, and where that protection ends.

In short: only connect AI apps you trust. Surehand's modes, approvals and Pause protect you against mistakes and against an AI app doing more than you want. They are not a sandbox.

What a script can do

ae_run_script can do anything an After Effects script can: change the project, read and write files anywhere your user account can, use the network, and run shell commands through system.callSystem (unless you block them). The AI app sends the script; After Effects runs it.

The access token

• The bridge inside After Effects listens on 127.0.0.1 only: other computers on the network can't reach it.
• Every request needs the token from ~/.surehand/ae/config.json. The file is readable only by you (mode 600 on macOS).
• Requests from web pages (with an Origin header) are refused, so a website you visit can't talk to the bridge.
• AI app settings don't contain the token: the AI app starts the server, and the server reads the token from config.json. (The one exception is the ChatGPT on the web address, which carries it; see below.)

What the token protects against: other user accounts on the computer, and programs that can't read your files.

What it doesn't: a program running as your own user account can read config.json, including the AI app itself. That's why approvals and Pause use a separate secret (below).

Changing the token

1. Delete the token line from ~/.surehand/ae/config.json.
2. Re-run the installer (it keeps an existing token, and makes a new one if there is none).
3. Restart After Effects and your AI apps.
4. If you use ChatGPT on the web, start the link again and paste the new address into the connector.

Pause AI and approvals

Answering an approval, pausing and resuming, and the panel's own actions need a panel secret:

• The bridge makes it when After Effects starts and keeps it only in memory.
• It hands it only to the Surehand panel and the approval pop-up, through After Effects' extension events, which only code running inside that After Effects' extensions can send or receive.
• It is never sent over the network or written to a file.

So an AI app, which has the token, still can't approve its own requests, can't resume after you pause it, and can't run anything while paused. Deleting "paused" from config.json doesn't resume either: the bridge holds the pause until you click Resume.

Approvals also guard against accidents: a new request can't be answered in its first second on screen, an answer only counts for the request on screen, and Enter never allows. See Approvals.

Modes and shell commands

Guardrail	What it does	Limit
Ask mode	Every change and every script waits for your Allow / Deny, with the exact code	Reading the project isn't held.
Read-only mode	Editing tools are refused; scripts that change the project are undone; some calls are refused before they run	A text check; a call assembled at runtime gets past it, and is then undone and reported. Files written by a script are not undone. See What the AI can do.
Shell commands in scripts: Off	Scripts that call system.callSystem are refused before they run	A script can still read and write files.
Settings file unreadable	Changes are refused (fails closed)	—

What is out of scope

• An AI app (or any program) with full shell access as your user account. For example, a coding agent allowed to run any command. It can read and change everything Surehand can, including config.json, the server and the extension files. Surehand's permissions are guardrails against mistakes, not a sandbox against such a program. If you need that boundary, run the agent under a different user account or in a sandbox.
• What the AI app sends to its own servers. Your prompts, and whatever the AI reads from your project (layer names, text, rendered frames it looks at), go to the AI provider like any other content in the chat. That is governed by your AI app and provider, not by Surehand.
• The safety of scripts you approve. Approval shows you the code; it can't judge it for you.

ChatGPT on the web

The secure link makes the server reachable from the internet, at an address that contains your token. Anyone with the address can control After Effects on your computer while the link runs.

• Don't share the address. Click Stop when you're done.
• Quick-tunnel addresses change on every start.
• Your mode, approvals and Pause apply as for any AI app.

See ChatGPT on the web.

The HTTP server (--http) requires the token, as an Authorization: Bearer header or as the last part of the address (/mcp/<token>). --no-auth turns that off; never use it with a tunnel.

Chat in After Effects

The panel's chat runs Codex, Claude Code or Antigravity on its own sign-in: Surehand never stores or handles an API key or a sign-in. The agent's calls are ordinary AI calls, so the mode, approvals, Pause and the activity log apply. The agent's shell, file edits and web access are switched off or not allowed for the chat. Antigravity's settings get one Surehand entry and one allow rule only after you click Connect (with a backup first); Disconnect and the uninstaller remove them. See Chat in After Effects.

Signed software

Part	How it is signed
After Effects extension	Signed with Adobe's ZXPSignCmd (self-signed certificate). After Effects checks the files against the signature and skips the extension if any file changed. No PlayerDebugMode needed.
Mac .pkg (1.4)	Signed with an Apple Developer ID and notarized by Apple.
Windows Setup .exe (1.4)	Authenticode-signed (Certum code signing certificate). The bundled node.exe keeps the OpenJS Foundation's own signature.
Zip launchers (.command, .bat)	Not signed or notarized. See Troubleshooting.

Downloads Surehand makes

What	When	Verified by
Node.js 22 (zip launchers)	Only if no Node.js is found	SHA-256 from nodejs.org's SHASUMS256.txt
Server updates	When you click Update now or run update	The SHA-256 GitHub publishes for the release file; the new server must start and report the expected version before it replaces the old one
FFmpeg 9.0.2 (Preflight)	Only after you agree (and approve it in Ask mode; never in Read-only mode)	A SHA-256 pinned in Surehand's source; must report the expected version
Update check	At most once a day, unless turned off	Reads the latest release's version from GitHub (pre-releases too, only with Beta updates on); installs nothing

Updates come only from the official release of ConformLabs/surehand-mcp.

AI app settings

Surehand changes an AI app's settings file only when it can read it. A file with a mistake in it is left as it is and reported. Before each change it makes a backup (see Installing) and writes atomically, so a crash can't leave half a file.

The activity log

Every call, with its full script code, is in ~/.surehand/ae/activity.jsonl on your computer. It's useful for reviewing what an AI did. It can contain project details (names, paths, text), so treat it like your project files when sharing. Copy diagnostics replaces the token with its length and includes only the first line of the last 15 calls.

Reporting a security problem

Please don't post details of a security problem in a public issue. Open an issue at ConformLabs/surehand-mcp asking for a private contact, and the details can be shared from there.