Connect your agent

Nano Helix exposes your live PyMOL viewer to an MCP client over a localhost bridge. It works with Claude Code, Codex, or anything else that speaks MCP.

The one-click path

Open Nano Helix, and in the sidebar click Connect Claude Code or Connect Codex. Nano Helix finds the CLI on your system and registers itself as an MCP server. Start a new conversation in your agent afterwards — MCP servers are picked up when a session starts.

That is the whole setup. Everything below is for when the one-click path cannot find your CLI, or you use a different agent.

Registering manually

Nano Helix ships its own MCP launcher: the same executable you already installed, started with --nanohelix-mcp. On macOS that is:

claude mcp add --scope user nanohelix -- \
  /Applications/NanoHelix.app/Contents/MacOS/NanoHelix --nanohelix-mcp

And for Codex:

codex mcp add nanohelix -- \
  /Applications/NanoHelix.app/Contents/MacOS/NanoHelix --nanohelix-mcp

On Windows, substitute the path to NanoHelix.exe where you installed it. If you are running Nano Helix from source, point the launcher at modules/pmg_qt/nanohelix_mcp_server.py with your Python interpreter instead.

The Agent bridge item in the Nano Helix sidebar always shows the exact launcher command for your install — copy it from there rather than guessing the path.

Any other MCP client

Nano Helix is a standard stdio MCP server, so any client works. The shape of the config, in the form most clients use:

{
  "mcpServers": {
    "nanohelix": {
      "command": "/Applications/NanoHelix.app/Contents/MacOS/NanoHelix",
      "args": ["--nanohelix-mcp"]
    }
  }
}

What your agent can reach

Four tools read state; one acts. Reading is genuinely narrow — the scene, your selection, and a screenshot on request, nothing more.

Acting is not narrow, and it is worth being precise about why. nanohelix_execute_pymol hands the agent the real PyMOL command line, and PyMOL evaluates Python. That is what makes it useful — anything you could type, it can run — but it also means the bridge is a narrow interface, not a security boundary. An agent you would not trust with your keyboard is an agent you should not connect.

Tool	Access	Does
`nanohelix_get_status`	read	Is Nano Helix running, and what is in the viewer.
`nanohelix_get_scene`	read	Objects, chains, atom counts, states, selections, camera view.
`nanohelix_get_selection`	read	Atoms and unique residues in the current `sele` selection.
`nanohelix_capture_viewport`	read	PNG of the current viewport. Never automatic.
`nanohelix_execute_pymol`	write	Run PyMOL commands in the live viewer. Anything the command prints is returned to the agent.

How the connection works

When Nano Helix starts, it binds an HTTP server to 127.0.0.1 on an ephemeral port and generates a fresh session token. Both are written to:

~/.nanohelix/runtime.json

The directory is created with 0700 and the file with 0600, so only your user can read it. The MCP launcher reads that file to discover the running instance, and every request must present the token as a bearer credential. The file is removed when Nano Helix quits.

Because the port and token are regenerated per session, there is nothing durable to leak and nothing listening when the app is closed. To relocate the file, set NANOHELIX_RUNTIME_FILE before launching both Nano Helix and the MCP server.

Troubleshooting

“Nano Helix is not running. Open Nano Helix and try again.” The launcher could not read the runtime file. Nano Helix must be open before your agent calls a tool — the bridge only exists while the app does.

“Nano Helix runtime information is invalid. Restart Nano Helix.” The runtime file exists but is missing its URL or token, usually after an unclean shutdown. Quit Nano Helix fully and reopen it.

The CLI was not found on PATH. The one-click button shells out to claude or codex, which GUI apps do not always inherit. The dialog prints the exact command to run yourself — see registering manually.

The agent does not see the tools. MCP servers are loaded at session start. Start a new conversation after connecting.

A request timed out. The bridge waits 65 seconds for PyMOL to answer. A command that opens a modal dialog in the viewer will block until you dismiss it.

Still stuck

Email support@nanohelix.ai. Including the launcher command from the Agent bridge dialog helps a lot.