Using Ornatrix with Claude
Ornatrix App can be driven from an external AI assistant such as Claude Desktop or Claude Code. Once connected, you can ask Claude to build and adjust grooms in your running copy of Ornatrix App, in the same conversation where you are doing everything else: reading reference material, looking at images, or working on other files.
This uses the Model Context Protocol (MCP), an open standard for connecting AI tools to applications. Ornatrix App exposes its grooming operations as MCP tools; the AI tool connects to your already-running copy of Ornatrix App over your own computer's local network interface.
If you would rather work inside Ornatrix App itself, see The Assistant, which does the same thing from a panel in the application. The two share the same underlying connection, and you can use either.
This feature is experimental and is turned off by default.
How it works
Ornatrix App listens for grooming commands on a local port. Nothing is exposed to the internet: the listener accepts connections only from your own computer, and only while Ornatrix App is running with the feature enabled.
The AI tool never launches Ornatrix App and never opens your groom files directly. It attaches to the copy of Ornatrix App you already have open and works on whatever groom is loaded, which means you can watch it work in the viewport as it goes.
Turning on the connection
- Open Settings and Preferences and set Interface.EnableControlEndpoint to on.
- Restart Ornatrix App. This setting is only read at startup.
Ornatrix App now accepts connections on port 8765 whenever it is running. If that port is already taken, set the ORNATRIX_MCP_PORT environment variable to a free port before starting Ornatrix App.
Connecting Claude Desktop
Ornatrix App ships an extension bundle named Ephere.Ornatrix.Mcp.mcpb, next to the Ornatrix App executable. Double-click it and Claude Desktop will offer to install it. Restart Claude Desktop afterwards, and the Ornatrix tools appear in your conversations.
If you changed the port above, set the same port in the extension's settings in Claude Desktop.
Connecting other MCP tools
Any MCP-capable client can connect, using the same executable over standard input and output. The details differ per client, but the command to run is always Ephere.Ornatrix.Mcp.exe from your Ornatrix App folder, with ORNATRIX_MCP_PORT in its environment if you changed the port. For a client configured with a JSON file, the entry looks like this:
{
"mcpServers": {
"ornatrix": {
"command": "C:\\Program Files\\Ephere\\Ornatrix App\\Ephere.Ornatrix.Mcp.exe",
"env": { "ORNATRIX_MCP_PORT": "8765" }
}
}
}
Adjust the path to match where you installed Ornatrix App.
What Claude can do
Once connected, Claude can inspect your scene and operator graph, create operators and connect them into the stack, read and change operator parameters, create a starting hair groom, open and save groom files, resolve asset search paths, render the viewport to an image and look at the result, and load or unload operator plugins.
Everything it does runs through the normal command stack, so Ctrl+Z in Ornatrix App undoes its work one operation at a time. An edit that would leave the groom in an invalid state is rejected and rolled back rather than applied.
A good way to work is to keep Ornatrix App visible beside the AI tool: you see each change appear in the viewport and the Operator Stack as it is made, and you can take over by hand at any point.
Security and privacy
The listener accepts connections from your own computer only. It is not reachable from your network or the internet.
Anything the AI tool reads from your groom - operator names, parameter values, and any viewport renders it takes - is sent to that tool's provider as part of your conversation, under that provider's terms. Ornatrix does not send anything anywhere on its own.
Because any local program could in principle connect to the listener, leave the setting off when you are not using it. You can require a shared secret by setting the ORNATRIX_MCP_TOKEN environment variable to the same value for both Ornatrix App and the AI tool.
Troubleshooting
The tools appear but every one of them fails. Ornatrix App is not running, or it was started without the setting enabled. The connection is made per command, so you can start Ornatrix App at any time and retry without restarting the AI tool.
Nothing appears after installing the extension. Claude Desktop must be fully quit and restarted, not just closed to the tray.
Commands fail after changing the port. The port must match on both sides: the ORNATRIX_MCP_PORT value Ornatrix App was started with, and the port configured in the AI tool.
It cannot be started at all. Confirm the setting is on and that Ornatrix App was restarted afterwards. Another running copy of Ornatrix App may already be using the port.
Related
- The Assistant - the same capability from inside Ornatrix App.
- Scripting with the Python Console - scripting the application directly.
- Settings and Preferences - where the setting lives.