Agent automation

The loop

1. 1.Edit. The agent changes the .mtlx file: by hand for parameter tweaks, or through a short script for graph edits.
2. 2.Check. mtlx check validates the document and reports issues as JSON, so mistakes are caught before rendering.
3. 3.Render. mtlx render draws the material with the same viewer as this site and writes a PNG.
4. 4.Look. Claude Code and Codex read images natively. The agent compares the render with the goal and edits again.

npm install -g mtlx-cli

# 1. validate the edit; exits non-zero and lists issues on failure
mtlx check material.mtlx --format json

# 2. render the material headlessly to a PNG the agent can look at
mtlx render material.mtlx -o preview.png
mtlx render material.mtlx -o sphere.png --geometry sphere --material Wood --size 512

# 3. inspect the document structure without opening it
mtlx info material.mtlx --format json

The PNG has a transparent backdrop by default, so the agent sees only the model and never has to separate it from the environment; --background environment shows the IBL instead. mtlx render runs headlessly in a Chromium-based browser already on the machine: Google Chrome, then Microsoft Edge, on macOS, Windows, and Linux. Nothing is downloaded at install time. Set MTLX_BROWSER or pass --browser to use a specific executable. A material that fails to compile exits non-zero with the viewer's error message, so the agent can read it and repair the file.

Structural edits with a script

Parameter changes are easiest as direct XML edits. For adding nodes, connecting inputs, or anything that must stay valid, mtlx-core/session gives the agent the same operations the Editor uses, with validation on every step. It runs in plain Node with no DOM or renderer.

import { readFile, writeFile } from 'node:fs/promises';
import { parseMaterialX } from 'mtlx-core';
import { createEditorSession } from 'mtlx-core/session';

const editor = createEditorSession({ document: parseMaterialX(await readFile('material.mtlx', 'utf8')) });
const graph = editor.graph('');

editor.transaction('Warmer, rougher wood', () => {
  graph.setInputValue('SR_wood1', 'base_color', [0.55, 0.32, 0.18], { type: 'color3' });
  graph.setInputValue('SR_wood1', 'specular_roughness', 0.7);
});

await writeFile('material.mtlx', editor.toXml());

See the mtlx-core README for the full session API: adding and removing nodes, connections, diagnostics, undo, and nested graphs.

As MCP tools

Hosts that speak the Model Context Protocol can register mtlx mcp once and call the same capabilities as tools: check_material, inspect_material, render_material, which returns the PNG inline, and edit_material, which runs a script against the session API and saves the file. Nothing else is installed; it is the same CLI on stdio.

claude mcp add mtlx -- mtlx mcp     # Claude Code
codex mcp add mtlx -- mtlx mcp      # Codex CLI

Telling the agent about it

Drop a few lines into the project's agent instructions file (CLAUDE.md, AGENTS.md, or equivalent) so the agent knows the tools exist and checks its own work:

# MaterialX materials in this repo

- Materials are .mtlx XML files. Edit them directly, or run a Node script against mtlx-core/session
  for structural changes (adding nodes, connecting inputs).
- After every edit run `mtlx check <file> --format json` and fix any error-level issue.
- Render with `mtlx render <file> -o <png> --geometry sphere` and look at the image before
  deciding the material is done. Render the totem too when roughness, coat, or metalness matter.
- Node definitions and their inputs are listed by `mtlx info <file> --format json`.

Working in the browser instead

Agents that drive a browser, such as Claude Code with the Claude in Chrome extension or any client with a Playwright MCP server, can open the Editor and Viewer here and take screenshots of the preview. The editor page exposes its live session as window.mtlx, so an agent can script edits with the same API as above instead of clicking through the graph, and the canvas and node graph update as it works.

// Run in the /editor page (Playwright evaluate, Claude in Chrome, or the devtools console)
const graph = window.mtlx.graph('');
window.mtlx.transaction('Warmer base color', () => {
  const color = graph.addNode({ definition: 'ND_constant_color3' });
  graph.setInputValue(color, 'value', [0.8, 0.2, 0.1], { type: 'color3' });
  graph.connect({ node: color, output: 'out' }, { node: 'surface', input: 'base_color' });
});
window.mtlx.toXml(); // the edited document, ready to save

That works for demos where a person watches along. For repeatable, scriptable results the CLI loop above is the recommended path.