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 works in the copy of Ornatrix App you have open, on whatever groom is loaded, which means you can watch it work in the viewport as it goes. It never opens your groom files itself. When Ornatrix App is not running it can start it, and when Ornatrix is not installed it can help you install it, but it asks you first each time (see Starting and installing Ornatrix below).
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.
A second copy of Ornatrix App started while one is running finds port 8765 taken and listens two ports up, on 8767, then 8769 for a third, and so on; its Console says which port it got. The AI tool finds the running copies by itself, and looks again when you restart Ornatrix App. With one copy running it uses that one. With several, it keeps to the copy it last worked with in the conversation, and otherwise asks you which one rather than guessing, since each copy has its own groom. To tie the AI tool to one particular copy, set that copy's port in the AI tool with the ORNATRIX_MCP_PORT environment variable. If something else has taken 8765, set ORNATRIX_MCP_PORT to a free port before starting Ornatrix App, and set the same port in the AI tool.
Connecting Claude Desktop or Claude Code
Open Settings, go to the Interface tab and scroll down to External AI Clients. It shows whether Ornatrix App is accepting connections and on which port, and has two buttons that copy what the AI tool needs, with the path of your installation filled in:
- Copy Claude Desktop configuration: in Claude Desktop open Settings, Developer, Edit Config, paste the entry into the file (merge it into the existing
"mcpServers"block if the file already has one), save it, and restart Claude Desktop. The Ornatrix tools then appear in your conversations. - Copy Claude Code command: run the copied command once in a terminal.
This is set up once. The connection keeps working across restarts of Ornatrix App and of the AI tool.
The MCP server comes with the AI Assistant component of the installer. If the section says it is not installed, run the installer again and select that component.
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 only if you want it tied to one particular copy of Ornatrix App.
The quickest way is to let it add itself. In a Command Prompt, run:
"C:\Program Files\Ephere\OrnatrixApp\Ephere.Ornatrix.Mcp.exe" install --client all
This adds an ornatrix entry to every MCP client it finds on your computer - Claude Desktop, Claude Code, Codex, Cursor, VS Code, Devin, Windsurf, Gemini CLI and Antigravity CLI - and leaves the rest of each client's settings as they were, keeping a copy of the file it changed. To pick clients, name them instead of all, as in --client cursor,codex. Add --dry-run to see what would change without changing anything, or --uninstall to take the entry out again. Then restart the client. A client added this way gets every tool except running scripts in Ornatrix App and closing it; for those, add --toolsets default,+admin.
To set up a client by hand, the entry for one configured with a JSON file looks like this:
{
"mcpServers": {
"ornatrix": {
"command": "C:\\Program Files\\Ephere\\OrnatrixApp\\Ephere.Ornatrix.Mcp.exe"
}
}
}
Adjust the path to match where you installed Ornatrix App.
What Claude can do
Once connected, Claude can inspect your scene and operator graph, including how the operators are connected, create operators and connect or disconnect them by name, read and change operator parameters (array parameters included), create a starting hair groom, find the MetaHuman .dna files on your machine and bring a head in from one (see MetaHuman Heads), import meshes from OBJ, FBX, Alembic and USD files, list the grooms installed with Ornatrix App, open and save groom files, resolve asset search paths, render the viewport to an image and look at the result, render the timeline to a video (see Rendering Videos), and load or unload operator plugins.
For game work it can take a groom all the way to hair cards: build the cards, report their polygon count, and export the card mesh to Alembic or USD (with the Unreal Engine preset if you ask for it) and the hair card atlas textures as one image per channel.
It can also read the guides that come with it, on building a groom, tuning an operator and the like, before it starts.
Everything it does runs through the normal command stack, so Ctrl+Z in Ornatrix App undoes its work, one step per command it ran. 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.
Starting and installing Ornatrix
The AI tool can find which Ornatrix products, and which applications they plug into (Maya, 3ds Max, Cinema 4D, Unreal Engine), are installed on your computer. It can start Ornatrix App when it is not running, and install an Ornatrix product. Each of these asks you first: in a prompt from the AI tool where it has one, otherwise in the conversation.
To install, it opens the product's download page on ephere.com in your own browser, where you sign in and download the installer yourself, so your account details never pass through the AI tool. It then checks that the file is an Ornatrix installer signed by Ephere and installs it, and Windows asks you for administrator rights as usual. An installer that is not signed by Ephere is never installed without you seeing it: it can only open that installer's own setup for you to go through.
The Ornatrix plugins for Maya, 3ds Max, Cinema 4D and Unreal Engine cannot be driven by an AI tool yet. It can install and start them, but it works on grooms in Ornatrix App only.
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. Web pages open in your browser cannot reach it either: the listener refuses any request a browser makes.
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. Ask the AI tool to start it, or start it yourself: the connection is made per command, so you can 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.
The AI tool asks which copy of Ornatrix App to use. Several copies are running and it has not worked with one of them yet in this conversation. Tell it which, for example by its port, which each copy's Console and the External AI Clients section in Settings report; it keeps to that copy afterwards. To tie the AI tool to one copy for good, set that copy's port in it with ORNATRIX_MCP_PORT.
A long command reports that Ornatrix App is still working. Rendering, exporting or baking a large groom can take minutes. The AI tool waits up to ten minutes per command and then reports that Ornatrix App is still busy rather than failing; the command carries on. Let it finish before asking again, so it is not applied twice.
Related
- The Assistant - the same capability from inside Ornatrix App.
- Scripting with the Python Console - scripting the application directly.