HoudiniMCP

by JTCHE

Overview Schema Source Related Servers Discussions Admin

Python

Local

session

Destructive

Report the Houdini sessions, choose one, or start, stop or interrupt one.

Instructions

Report the Houdini sessions, choose one, or start, stop or interrupt one.

Actions: status, list, attach, detach, interrupt, start, start_gui, stop.

Use it first when a tool says that Houdini is not reachable, and use it to
learn the Houdini version before you use an API that changed between
releases.

Several Houdini sessions can listen at the same time: the graphical one that
holds the work of the user, and a headless one for your own tests. Every
tool result names the session that answered, in `_session`. Read that line
when a scene looks empty or wrong: an empty scene is usually the wrong
session, not a lost scene.

Do not use it to read the scene: scene_overview does that.

action:
    "status"    — the session that the bridge talks to now, the other
                  sessions, and the port. Starts nothing, and always
                  answers.
    "list"      — every Houdini that runs, with its version, its process
                  id, its .hip file, whether it has a window and whether it
                  answers; and the Houdini versions installed.
    "attach"    — send every later command to the Houdini on `port`. Use it
                  when "list" shows more than one.
    "detach"    — forget the attached port and let the bridge choose again.
    "interrupt" — stop the call that runs now in the attached Houdini, or
                  in the one on `port`: a script past its budget, a loop
                  that will not end. Houdini answers again after it. A
                  single long cook does not return to Python; then, in a
                  Houdini with a window on Windows, it sends Escape to
                  the window, as the user would. A stopped simulation
                  keeps a partial cache.
    "start"     — start a headless Houdini (hython) and attach to it.
                  `version` chooses the release, for example "21.0" or
                  "21.0.829"; without it, the version of the Houdini window
                  that runs. A Houdini that already runs is not touched, so
                  this is the safe way to test while a person works.
    "start_gui" — start Houdini with its window and wait for the plugin to
                  answer, up to 4 minutes. It opens the .hip file at `hip`
                  when you give one, it stays open when the bridge stops,
                  and the bridge attaches to it. `version` as for "start".
    "stop"      — stop the headless Houdini that this bridge started. A
                  Houdini that you started yourself, or with "start_gui", is
                  not touched.

Returns JSON. The report says what to do next when nothing answers.

Input Schema

Name	Required	Description	Default
`hip`	No	start_gui: the .hip file to open.
`port`	No	attach: the port of the Houdini to talk to, from list. interrupt: the Houdini to interrupt, when not the attached one.
`action`	No	One of "status", "list", "attach", "detach", "interrupt", "start", "start_gui", "stop".	status
`version`	No	start and start_gui: the Houdini release, for example "21.0" or "21.0.829".

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed20 schema fields changedv0.7.3Oct 4, 2026

removedInput schema / properties / action / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedInput schema / properties / action / description

Added value: +"One of \"status\", \"list\", \"attach\", \"detach\", \"interrupt\", \"start\", \"start_gui\", \"stop\"."

removedInput schema / properties / action / title
```
Removed value: -"Action"
```
addedInput schema / properties / action / type
```
Added value: +"string"
```

removedInput schema / properties / hip / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / hip / default
```
Removed value: -null
```

addedInput schema / properties / hip / description

Added value: +"start_gui: the .hip file to open."

removedInput schema / properties / hip / title
```
Removed value: -"Hip"
```
addedInput schema / properties / hip / type
```
Added value: +"string"
```

removedInput schema / properties / port / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / port / default
```
Removed value: -null
```

addedInput schema / properties / port / description

Added value: +"attach: the port of the Houdini to talk to, from list. interrupt: the Houdini to interrupt, when not the attached one."

removedInput schema / properties / port / title
```
Removed value: -"Port"
```
addedInput schema / properties / port / type
```
Added value: +"integer"
```

removedInput schema / properties / version / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / version / default
```
Removed value: -null
```

addedInput schema / properties / version / description

Added value: +"start and start_gui: the Houdini release, for example \"21.0\" or \"21.0.829\"."

removedInput schema / properties / version / title
```
Removed value: -"Version"
```
addedInput schema / properties / version / type
```
Added value: +"string"
```
removedInput schema / title
```
Removed value: -"toolArguments"
```

Addedv0.1.1Oct 4, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark the tool non-read-only and destructive, and the description goes well beyond them: it says start never touches a running Houdini, stop only kills bridge-started headless sessions, start_gui waits up to 4 minutes and survives bridge exit, interrupt may send Escape on Windows, and an interrupted simulation leaves a partial cache. It also discloses the per-result `_session` field, which explains confusing empty-scene results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded with a one-line summary, an action index, and usage guidance before the long action glossary, so the most important content comes first. It is long for a single description, but the length is warranted by eight distinct actions; a few phrases are marginally redundant but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-action lifecycle tool this covers everything an agent needs: which action to pick, what each does to processes and files, timeout behavior, and how to detect the wrong session. An output schema exists, so return format is correctly left out, with only the `_session` convention noted because it affects interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: version accepts partial or full releases and defaults to the running window's version, port comes from list and is used differently by attach vs interrupt, and hip is only meaningful for start_gui. These per-action scoping details are not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line gives a specific verb set and the exact resource: report Houdini sessions, pick one, start/stop/interrupt. It further distinguishes itself from scene_overview and lists all eight actions up front, so an agent can tell what it does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names concrete trigger conditions ('use it first when a tool says that Houdini is not reachable', 'use it to learn the Houdini version before an API that changed') and an explicit exclusion ('Do not use it to read the scene: scene_overview does that'). It also tells the agent when to use attach ('when list shows more than one').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server