Connecting AI Agents to Octane Standalone (MCP)

Octane MCP | ~2,353 words, 12 min read

About This Guide

This guide walks through turning on the MCP server that's built into Octane Standalone, connecting an AI agent to it (a coding agent such as Claude Code, Codex, Cursor, VS Code or Gemini CLI, or the Claude and ChatGPT desktop apps), and what that agent can actually do once it's in.

Intro and Overview

MCP (Model Context Protocol) is an open standard that lets AI agents use tools inside other applications. Octane Standalone 2027.1 ships with an MCP server built in. It runs on our own machine while Octane is open, and it hands the agent exactly one tool: octane_lua.

That tool runs a Lua script inside Octane and sends back whatever the script prints. One tool sounds small, but Octane's Lua API reaches almost everything: creating and wiring nodes, setting pins, writing and compiling OSL, building Vectron geometry, rendering, saving images, and saving projects and packages. The agent writes the Lua, Octane runs it, and the agent reads the result and decides what to do next.

The mosaic in the header image was made exactly that way: an agent wrote a scripted graph (a custom node with sliders) that turns flat artwork into a tiled mural, then lit it, framed it and rendered it, all through MCP.

What We'll Need

• Octane Standalone 2027.1 or later. The MCP server lives in its Preferences. (This guide was made with OctaneRender Studio+ 2027.1 Beta 1 on Windows.)
• An agent that speaks MCP: Claude Code, Codex, Cursor, VS Code, Gemini CLI or any other client that supports streamable HTTP, or the Claude or ChatGPT desktop app. No terminal is needed for the desktop apps.
• For the Claude desktop app only: Node.js (the LTS version from nodejs.org). Claude's config file starts a small bridge that runs on Node. The other agents connect to the URL directly.
• Both on the same machine. The server address is localhost, so the agent has to run on the computer that runs Octane.

Turn On the MCP Server

1. Open File > Preferences (Ctrl + ,).
2. On the Application page, scroll to the Agentic MCP server section.
3. Leave the HTTP port at 8180 unless something else on the machine already uses it.
4. Tick Run on application startup so the server is there every time Octane opens.
5. Check that Server status reads Listening, with the URL http://localhost:8180/mcp. If it doesn't, start the server with the button on the right (it reads Stop MCP server while the server is running).

That URL is what every agent connects to. If we change the port, the URL changes with it (http://localhost:<port>/mcp).

Connect Your Agent

Pick the agent we're using and follow its steps. There's no account to sign in to and no API key: the server is local, so connecting is just pointing the agent at the URL.

Claude Code

1. Add the server from a terminal:

claude mcp add octane --scope user --transport http http://localhost:8180/mcp

If Claude Code is already running, restart it so it picks up the new server. Run /mcp and octane should be listed as connected.

Codex

codex mcp add octane --url http://localhost:8180/mcp

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "octane": { "url": "http://localhost:8180/mcp" }
  }
}

VS Code

Open the Command Palette, run MCP: Add Server, choose HTTP, paste the URL and name it octane:

http://localhost:8180/mcp

Gemini CLI

gemini mcp add --scope user --transport http octane http://localhost:8180/mcp

Connect a Desktop App

Not a terminal user? The Claude and ChatGPT desktop apps can drive Octane too, from an ordinary chat window. Both run on the same computer as Octane, so they can reach localhost.

Claude Desktop

Claude's desktop app starts local MCP servers from its config file. That file expects a program to launch, and Octane's server speaks HTTP, so the entry runs mcp-remote, a small bridge that connects the two:

1. Install Node.js if it isn't on the machine yet.
2. In the Claude app, open Settings (from the Claude menu on macOS, or the menu in the top-left corner on Windows), choose Desktop app, then click Manage next to Extensions. Scroll down to Local MCP servers and click Edit config. This opens claude_desktop_config.json (on Windows it's in %APPDATA%\Claude\, on macOS in ~/Library/Application Support/Claude/).
3. Add Octane to the mcpServers section and save the file:

{
  "mcpServers": {
    "octane": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8180/mcp", "--transport", "http-only"]
    }
  }
}

• If the file already lists other servers, add only the "octane": { ... } block, with a comma after the server before it.
• Quit Claude completely (from the tray icon on Windows, or Claude > Quit on macOS) and open it again. Closing the window isn't enough.
• Check it's connected: back in Settings > Desktop app > Extensions, octane should be listed under Local MCP servers marked Running. It also shows up under the + button in a chat, in Connectors.

Then try the check prompt from the next section in a new chat. Claude asks before it runs each tool; allow it.

If Octane doesn't show up

• Make sure Octane is open and its MCP status reads Listening. Claude starts the bridge when the app opens, so open Octane first, or restart Claude after opening Octane.
• Check the JSON is valid: a missing comma or quote stops every server in the file from loading.
• On macOS, if the log says npx can't be found, the app isn't seeing the terminal's PATH. Run which npx in Terminal and put that full path in "command" (for Homebrew it's usually /opt/homebrew/bin/npx).
• Read the logs: click View logs next to Octane, or open %APPDATA%\Claude\logs\mcp-server-octane.log on Windows, ~/Library/Logs/Claude/mcp-server-octane.log on macOS.

ChatGPT Desktop

The ChatGPT desktop app connects to local MCP servers directly, with no bridge and no Node.js:

1. Open Settings and choose Plugins (under Integrations), then the MCPs tab. In some versions the page is called MCP servers; typing MCP into the settings search box finds it.
2. Click Add (top right) and choose the custom MCP option to open Connect to a custom MCP.
3. Name it octane, set Type to Streamable HTTP, and paste the URL:

http://localhost:8180/mcp

• Leave the bearer token and header fields empty (the server has no sign-in) and click Save. Restart the app if it asks.
• Back on the MCPs tab, octane should be listed under Servers with its switch on.

The desktop app shares its MCP settings with Codex: a server added with codex mcp add shows up in the app too, and the other way round.

Running the Agent in WSL?

This only affects terminal agents: the desktop apps run on Windows itself and reach Octane directly. On Windows, localhost inside WSL doesn't reach Windows apps under WSL's default networking. Either run the agent on Windows itself, or turn on mirrored networking: add networkingMode=mirrored under [wsl2] in %UserProfile%\.wslconfig, then run wsl --shutdown and reopen the terminal.

Check the Connection

Before building anything, ask for something harmless that proves the round trip works:

"Use the octane_lua tool to print the path of the open project and how many items are in its scene graph."

The agent should run something like this, and report back the path (empty for an unsaved project) and a count:

print(octane.project.getCurrentProject())
print(#octane.project.getSceneGraph():getOwnedItems(), "items")

If that comes back, everything is wired up.

What the Agent Can Do

Build and Wire Scenes

Create nodes, connect them, set pin values: geometry, materials, textures, environments, lights, cameras, render targets. Anything we'd do in the node graph editor by hand, the agent can do in a script, including laying the nodes out neatly.

Write Shaders and Read the Errors

The agent can write an OSL texture or a Vectron (OSL signed-distance geometry), compile it in Octane, and read back whether it compiled and the exact error and line if it didn't. That loop of write, compile, fix is what makes procedural work through an agent practical.

Render and Look

A script can render a render target to a set number of samples and save the image to disk. Agents that can view images then open the result and judge it, so we can ask for changes in plain language ("the key light is too hot, warm it up") and get a new render back.

Make Custom Nodes with Sliders

Scripted graphs are Octane's custom nodes: Lua that defines real input pins with sliders and rebuilds its contents whenever a pin changes. An agent can write one, and from then on it's an ordinary node anyone can drive from the Node Inspector, no agent required. The mosaic tool is one of these.

Save and Package

Projects save as .ocs, and scenes package as .orbx, so the results move on to other machines, other DCCs or the Render Network.

How the Tool Behaves

A few details of octane_lua explain most of the surprises people run into:

• Each call starts fresh. Nothing (variables, functions, loaded modules) carries over between calls, so each script has to find the nodes it needs again, usually by name. Longer tools work best as .lua files on disk that a short script loads with dofile.
• Only print() comes back. io.write output isn't captured.
• Output is capped at 1,024 bytes by default. For anything longer, the agent should raise maxResultBytes (up to 1 MB), or the output arrives cut short.
• Calls time out at 60 seconds by default, 600 at most (timeoutSeconds), and that includes waiting for Octane to be free. Renders longer than that need to be split over several calls.
• Calls run one at a time, on Octane's main thread. The UI waits while a script runs.
• Scripts can take arguments: args arrive as arg[1] to arg[n].

Good Habits

• Name the agent's nodes. Ask it to prefix everything it creates (for example claude_), so its work is easy to tell apart from ours and to clean up.
• Ask for a tidy graph. New nodes land at the same spot and stack. Ask the agent to lay out every node in the same step that creates it.
• Keep the GPU free while it renders. The agent's renders are real Octane renders, so other GPU-heavy work slows both down.
• Have it look things up, not guess. Calling Octane's native functions with made-up arguments can crash Octane. The API documents itself (octane.help, octane.apiinfo), so ask the agent to check there first.
• Review the images, not just the logs. A script that ran without errors can still render the wrong thing.

Prompts to Try

• Studio setup: "Set up a product shot: daylight environment, a ground plane with a soft grey material, a thin-lens camera at eye level. Render 128 samples and show me the image."
• Shader work: "Write an OSL texture for weathered copper with verdigris in the crevices, compile it in Octane, fix any errors, and put it on the selected mesh."
• Custom tool: "Make a scripted graph node that builds a spiral staircase with sliders for steps, radius, height and rail thickness."
• Batch renders: "Render every render target in this project at 256 samples and save them as PNGs next to the project file."
• Housekeeping: "Lay out the node graph in tidy rows that flow down into the render target, and label the groups."

Common Questions

Do I need an API key or an account?

No. The server is local and has no sign-in. The agent itself may need its own account with its provider.

Can I add Octane as a custom connector on claude.ai or in ChatGPT on the web?

No. Web connectors are reached from the provider's servers, and Octane's server is only on our own machine (and shouldn't be put on the internet, since it runs any Lua it's given). Use a desktop app or a terminal agent.

Which should I use: a desktop app or a coding agent?

Both drive the same tool. The desktop apps are the easiest start and are great for asking for scenes, looks and renders. Coding agents are better for longer builds such as custom nodes and shader libraries, because they can also write files on disk for Octane to load.

Can the agent reach Octane on another computer?

Not through this guide's setup. The server address is localhost, so the agent and Octane run on the same machine.

Why did the output stop partway?

The default output cap is 1,024 bytes. Ask the agent to raise maxResultBytes on its calls.

Why did a long render fail?

A single call can run for at most 600 seconds. Longer renders need to be started in one call and checked on in the following ones.

Can I change the port?

Yes, in the Agentic MCP server preferences. Update the URL in the agent's settings to match.

Will it change my scene?

Only if we ask it to, but it can. The tool runs any Lua it's given against the open project, so save first.

Wrap Up

Once the server is listening and the agent is connected, Octane becomes something we can talk to: describe a scene, a shader or a tool, and the agent builds it in the node graph where we can see it, render it and keep working on it by hand.

Author's Notes

Written by Spenser Dickerson. ©2026 OTOY Inc.