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.
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.
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.
The connection
There is nothing to switch on. Ornatrix App accepts connections on port 8765 whenever it is running, and each connection has to present a secret which the App generates at startup and leaves among your own user files, so only a program running as you can use it. The secret changes every time Ornatrix App starts, and the tools below read it as they go, so this costs you nothing to keep working.
If port 8765 is already taken - by a second copy of Ornatrix App, for instance - set the ORNATRIX_MCP_PORT environment variable to a free port before starting Ornatrix App, and set the same port in the AI tool.
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, and a connection which does not present the current secret is refused, so another user's program on the same machine cannot drive your grooms.
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.
If you would rather choose the secret yourself - to connect from a tool which cannot read your user files, for example - set the ORNATRIX_MCP_TOKEN environment variable to the same value for both Ornatrix App and the AI tool. That value is then used instead of the generated one.
Troubleshooting
The tools appear but every one of them fails. Ornatrix App is not running. 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. Another running copy of Ornatrix App may already be using the port; give this one a port of its own as described above.
Related
- The Assistant - the same capability from inside Ornatrix App.
- Scripting with the Python Console - scripting the application directly.