HoudiniMCP

Overview Schema Source Related Servers Discussions Admin

session

Destructive

Report, attach to, start, stop, or interrupt Houdini instances, and list installed versions; use it when Houdini is unreachable or you need another target.

Instructions

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

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.
    "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

TableJSON 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

TableJSON 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?

Despite coverage from annotations (destructiveHint=true), the description adds substantial behavioral detail: start does not touch an already-running Houdini, stop only kills the bridge-started headless instance, start_gui waits up to 4 minutes and stays open after the bridge stops, interrupt restores Houdini responsiveness. No contradiction with a process-control tool being flagged destructive.

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?

Front-loaded purpose, then guidance, then a scannable per-action breakdown. It is long, but nearly every line carries operative information; only the _session explanation edges toward repetition of the result-handling theme.

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?

An output schema exists, so return formatting need not be described, and the description still notes that results name the answering session in `_session` and that the report says what to do when nothing answers. For an eight-action stateful tool this is complete enough to invoke safely.

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 meaning beyond it: version accepts a partial release like '21.0' and defaults to the running window's version, and port's role differs per action (attach vs interrupt). hip is tied specifically to start_gui.

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?

Opens with a specific verb set and resource: reporting, choosing, starting, stopping, or interrupting Houdini sessions. It explicitly distinguishes itself from sibling scene_overview, so an agent can tell it apart without opening schemas.

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?

Gives explicit triggers ('Use it first when a tool says that Houdini is not reachable') and an explicit exclusion ('Do not use it to read the scene: scene_overview does that'). Each action's use case is spelled out, e.g. attach 'when list shows more than one', interrupt for a runaway script.

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

Deploy Server