MoonRay MCP

An independent Model Context Protocol server for rendering, inspecting, and diagnosing OpenMoonRay scenes.

MoonRay MCP gives an MCP-compatible client typed control over a local MoonRay runtime. It supports Houdini's husk and HdMoonrayRendererPlugin, an optional native hd_render control host, and MoonRay's standalone viewer. Batch renders run in separate processes so a renderer failure does not take down the MCP server.

Naming

The GitHub repository is named moonray_mcp to follow the underscore-based naming used by related MoonRay component repositories. The installable Python distribution and command use moonray-mcp, while the Python import package is moonray_mcp.

Related MCP server: vred-mcp

What it provides

• moonray_health: verify the staged runtime, tools, and Hydra delegate

• moonray_capabilities: describe supported inputs and implemented controls

• moonray_resources: check memory, disk, load, and competing render processes

• inspect_scene: summarize a USD stage and recommend an authored camera

• launch_interactive_viewer: open USD or RDL in MoonRay's standalone viewer

• switch_interactive_viewer_aov: select a named AOV in the live viewer

• set_interactive_viewer_exposure: adjust live display exposure

• set_interactive_viewer_denoising: turn live denoising explicitly on or off

• capture_interactive_viewer_snapshot: save raw EXR and visible display PNG snapshots

• interactive_viewer_preview: return the visible viewer image directly to the client

• interactive_viewer_status / stop_interactive_viewer: inspect or close it

• validate_scene: preflight USD and RDL scenes

• inspect_materials: explain source shaders, MoonRay translations, textures, active lobes, and unsupported MaterialX nodes

• start_render: enqueue a process-isolated render and return a stable job ID

• render_status: inspect an active or saved job

• pause_render / resume_render: control an active native-host render

• resume_from_checkpoint: start a new native render from a saved recovery point

• capture_render_snapshot: write a live EXR and PNG from the native render buffer

• render_preview: return the latest live or completed PNG preview

• cancel_render: stop a queued or active render

• render_result: return the JSON report and PNG preview

• compare_renders: compare completed jobs or image files and return linear error metrics plus EXR and PNG difference images

• run_comparison_manifest: reproduce a named set of comparisons with optional expected RMS values and tolerances

Native jobs can select a primary Hydra AOV such as color, normal, depth, primId, primvars:name, lpe:expression, or shader:name. Live and final snapshots preserve that selection in the job report.

Native color and beauty jobs can also set denoise=true to apply Intel Open Image Denoise (OIDN) to the beauty output. Denoising defaults to off, is recorded in the job report, and is rejected for diagnostic AOVs and the husk backend. Albedo and normal guidance remain off in this first control slice.

Set samples=64 on a native job to request 64 uniform samples per pixel. The MCP translates total samples per pixel into MoonRay's square-root convention, so 64 is passed to the renderer as pixel_samples=8. Sample overrides must be perfect squares; leaving samples unset preserves the value authored in the scene.

Native color and beauty jobs can set checkpoint_interval_seconds to write a resumable EXR while rendering. After a checkpoint is ready, canceling or losing the original process does not discard that work: resume_from_checkpoint starts a new job with the same request and records its parent job and source checkpoint. Resume is rejected if the source USD changed after the checkpoint was created. The normal beauty EXR and PNG preview are extracted without modifying MoonRay's resumable channels and metadata.

Each job preserves its source hash, settings, resource preflight, native MoonRay progress, estimated time remaining, renderer log, translated RDL, beauty EXR, PNG preview, image statistics, diagnostics, timing, and peak process memory in a versioned JSON report.

Interactive viewer

launch_interactive_viewer opens a visible moonray_gui_v2 window without a Houdini viewport. USD input is converted to MoonRay RDL first with hd_usd2rdl; RDL input opens directly. The tool accepts resolution, frame, camera, free-camera mode, and auto, xpu, vectorized, or scalar execution modes. It returns a stable viewer ID for interactive_viewer_status and stop_interactive_viewer, plus paths to the translated scene, viewer log, optional final EXR, and durable JSON report.

Viewer launches include beauty, albedo, normal, depth, and wireframe displays. Use switch_interactive_viewer_aov to select one by name while the window is open. Launches can also override the scene's samples per pixel with a perfect square value. Exposure, denoising, and snapshots can be controlled while the viewer remains open. Each snapshot includes a raw EXR for downstream work and a PNG matching the currently visible AOV, exposure, denoising, and display transform. Live status reflects changes made through either MCP or the viewer UI. The viewer's native , and . keys still cycle backward and forward.

interactive_viewer_preview can capture and return that visible PNG as MCP image content, so the current AOV and display treatment appear directly in a client rather than only as a filesystem path. Set capture=false to return the most recent viewer snapshot without writing a new one.

Only one viewer or batch renderer is admitted at a time. Closing the MCP server also closes any viewer it owns, so an abandoned client cannot leave a hidden renderer running.

Scene inspection

inspect_scene opens a USD stage read-only through Houdini's OpenUSD runtime. It reports stage units and time range, prim and scene-element counts, authored cameras, lights, render products, unresolved asset attributes, and a suggested camera. An authored render-product camera wins; otherwise a clearly named shot, render, main, or hero camera is preferred before falling back to the first camera. The recommendation is reported explicitly and never modifies the scene.

Requirements

• macOS with Python 3.11 or newer

• Houdini 22 with husk, USD tools, and OpenImageIO tools

• a staged MoonRay Houdini runtime containing HdMoonrayRendererPlugin

• libcomputation_progmcrt.dylib in the runtime's lib directory

• hd_usd2rdl and moonray_gui_v2 for standalone USD viewing

MoonRay itself is not bundled with this repository. Build and stage OpenMoonRay separately, then point this server at that runtime.

Install

python3.11 -m venv .venv
.venv/bin/pip install -e .

Configure the runtime and output directory:

export MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime
export MOONRAY_MCP_OUTPUT_ROOT=/absolute/path/to/moonray-mcp-jobs

MOONRAY_MCP_RUNTIME defaults to ~/.local/share/moonray-mcp/runtime, and MOONRAY_MCP_OUTPUT_ROOT defaults to ~/.local/share/moonray-mcp/jobs. MOONRAY_MCP_SETUP_SCRIPT can override the expected runtime setup script. MOONRAY_MCP_NATIVE_HOST optionally selects a controllable hd_render build; otherwise the server looks for bin/hd_render inside the staged runtime. MOONRAY_MCP_USD_TO_RDL and MOONRAY_MCP_INTERACTIVE_VIEWER can override the translator and standalone viewer executables.

start_render uses the certified husk backend by default. Set its backend argument to native to opt into live status, pause, resume, snapshot, and cooperative cancellation through the control host. Set aov to select the native render buffer; non-color AOV selection is intentionally rejected by the default husk backend until a scene-safe render-product overlay is available.

Run the stdio server with:

.venv/bin/moonray-mcp

An MCP client registration example is available at examples/mcp.json.

The Zeltner regression example at examples/regressions/zeltner.json uses MOONRAY_ZELTNER_FIXTURE_ROOT to locate its external image set and preserves the historical RGBA metric convention explicitly.

Safety model

The server binds no network port and exposes no arbitrary command execution. Scene paths, camera paths, resolution, and job IDs are validated. Renders are serialized through one worker, source scenes are never modified, and launch is blocked when memory or disk space is critical or another local MoonRay render is already active.

Development

.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q src/moonray_mcp

Run the opt-in Cornell render certification against a configured runtime with:

MOONRAY_MCP_INTEGRATION=1 \
MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime \
  .venv/bin/python -m unittest tests.test_cornell_integration -v

Certify the native control path separately after installing a controllable hd_render host:

MOONRAY_MCP_NATIVE_INTEGRATION=1 \
MOONRAY_MCP_RUNTIME=/absolute/path/to/openmoonray-houdini-runtime \
MOONRAY_MCP_NATIVE_HOST=/absolute/path/to/hd_render \
  .venv/bin/python -m unittest tests.test_cornell_integration -v

The current implementation plan and future phases are documented in docs/roadmap.md.

Status

Version 0.1.0 establishes the MCP protocol, resource admission, persistent job model, output validation, and failure reporting. The full Cornell-box path is certified through the MCP at 128x128, including active-render cancellation with durable provenance and orphan-process checks. Native MoonRay progress is certified through both completed and actively canceled MCP jobs. Material inspection covers source USD, translated RDL snapshots, missing textures, UDIMs, and .tx availability. The comparison workflow adds durable RMS, mean, peak-SNR, and maximum-error reports without grading visual equivalence. The earlier render-preparation crash was traced to stale DwaBase-derived material DSOs after an ABI-changing header update; rebuilding all dependent DSOs resolved it. The native hd_render backend is certified through the MCP for status, stable pause/resume, live snapshots, cooperative cancellation, and orphan cleanup. Primary AOV selection and live retrieval are also certified with the Cornell fixture's normal AOV. Automatic beauty checkpoints and cross-process resume are certified through a 256x256 Cornell job that saved a checkpoint, canceled its original process, and completed from a new process.

License

The original code and documentation in this repository are licensed under the Apache License 2.0.

MoonRay, OpenMoonRay, Houdini, and other external applications, libraries, and assets are not distributed as part of this repository. They remain subject to their respective licenses and trademarks. The Apache 2.0 license for this project does not grant rights to those separately distributed components.