MCP Server (AI Agents)

The editor has a built-in MCP server — a way for AI agents such as Claude Code, Claude Desktop and other clients of the Model Context Protocol to see and operate the editor the way a person does. With the server enabled you can ask an agent to build or tune an effect for you, and watch every step happen live in the editor.

The server is off by default. It only ever listens on 127.0.0.1 (your own computer), so nothing outside your machine can reach it.

Enabling the server

There are two ways to switch the server on.

From Editor Settings

Open Windows → Editor Settings... and tick Enable MCP server in the MCP Server (AI Agents) group. The change applies immediately, no restart needed, and is remembered across editor runs.

The Port field picks the TCP port the server listens on. It defaults to 3742, and keeping it fixed is the point: you register the editor with your agent once, and the address keeps working across editor restarts. If the port is already taken by another program (or a second editor), pressing OK shows an error and reopens the dialog so you can pick a different number.

From the command line

The command-line switch wins for that run and does not change the saved setting — handy for scripts that launch an editor for one agent session:

# Windows
editor.exe --mcpServer=3742

# macOS
/Applications/NeutrinoParticlesEditor.app/Contents/MacOS/editor --mcpServer=3742

# Linux
./<editor>.AppImage --mcpServer=3742

Whichever way you enable it, the editor log (and the console, when started from a terminal) shows the address:

[MCP] Server listening on 127.0.0.1:3742

Connecting an agent

Any MCP client can connect over Streamable HTTP. The endpoint is always:

http://127.0.0.1:<port>/mcp

Claude Code — register the editor once, with the fixed port you chose:

claude mcp add --transport http --scope user npeditor http://127.0.0.1:3742/mcp

Claude Desktop connects to MCP servers as local commands rather than URLs, so it reaches the editor through the mcp-remote bridge. Add this to claude_desktop_config.json, then quit and restart the app:

{
  "mcpServers": {
    "npeditor": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3742/mcp"]
    }
  }
}

The config file lives in %APPDATA%\Claude\ on Windows and in ~/Library/Application Support/Claude/ on macOS. npx comes with Node.js, which this route needs.

Other clients follow their own registration flow; all they need is the URL above.

Checking that it works

Start the editor with the server on, then ask the agent something simple, such as "what do you see in the editor?". It will call the editor's status tool and describe the open projects and the current effect. If instead it reports that it cannot reach the server, work through this list:

• Is the editor actually running, with the checkbox ticked (or started with --mcpServer)?
• Does the port in your client match the one in the editor log line above? A bare --mcpServer picks a different port every run — use a fixed number for a registration you keep.
• Is the agent on the same computer? The server refuses anything that is not 127.0.0.1, by design.
• Did the editor report the port as busy on startup? Another program — often a second editor — already holds it; pick another number.

What an agent can do

The agent sees the editor as a live tree of named UI elements — every panel, button, checkbox and menu — so anything you can click, it can click: the Emitter Guide, the block scheme, graphs, the in-preview path, collision, area and grid editors, the preview scene and the timeline. On top of that it has tools for the things clicking cannot express: opening and creating projects and effects, taking screenshots of the preview to actually see what it is building, and exporting.

Two properties are worth knowing:

• Everything lands in your undo history. One undo step per action, so anything an agent did can be rolled back the usual way.
• Exports follow the same rules as the Export button — the same account and plan checks, the same progress window, the same post-export command.

Reporting problems to us

If an agent runs into something it cannot reach, behaviour that looks wrong, a bug, or simply an awkward corner of the editor, it can send a short report straight to the NeutrinoParticles team — optionally with screenshots of what it was looking at. Agents are also told to report capabilities that work but are documented nowhere, which is often how we learn a feature is hard to find.

This is one of the most useful things the integration gives us, so if your agent offers to send a report, please consider letting it:

• You see it before it goes. Agents are instructed to show you the exact title, text and attachments and get your consent first. A report can include screenshots of your effect, so read it as you would any outgoing message.
• It needs a signed-in account, since signing in is a human action.
• Only the editor version, your operating system and the active renderer are attached automatically — never file paths or project names.

What stays in your hands

A few things are deliberately reserved for the human at the keyboard:

• Signing in is yours alone. Agents can check whether you are signed in and whether your plan allows exporting, but they cannot log in, cannot read or type credentials, and are instructed to ask you to sign in through the editor's Account button when an export needs the server.
• Nothing is saved or discarded silently. An agent can close the editor, but if there is unsaved work the usual save prompt appears and the agent cannot answer it for you — it has to show you the question. Agents are also told to ask before closing an editor they did not start themselves, since it may be your working session.
• Exports run under a progress window. While an agent exports, the editor shows the same progress dialog as a manual export. It blocks stray edits (yours and the agent's alike) so the files being written stay consistent, and you can press Cancel at any time to stop the remaining items.
• You can always take over. The editor stays a normal, interactive editor while the server runs. Anything the agent did is in the undo history, and closing the editor — or just switching the checkbox off — ends the agent's access instantly.

Practical notes

• The server accepts connections only from the same computer (127.0.0.1). To use an agent from another machine you would have to build your own tunnel — nothing is exposed by default.
• One agent action executes at a time; the editor stays responsive between actions.
• Screenshots need the editor window visible on screen (not minimized).
• Debug-heavy effects can make the preview resimulate for a while after an edit; agents are told to wait for the preview to settle before taking screenshots, so do not be surprised by short pauses.
• If you use the editor and an agent at the same time, an open menu or a modal dialog temporarily blocks the agent's model-changing tools — it resumes once the dialog is closed.