cl0nazepamm/3dsmax-mcp/3dsmax-mcp-dev

3ds Max MCP — Agent Guide

Each tool's description documents its parameters, modes and limits. This guide covers what no single tool can: routing, tool choice, cross-tool workflows, safety rules and MAXScript pitfalls.

Tool Profile Routing

• Full/core: operational tools such as query_scene and create_object are advertised directly; call them by name.
• Progressive: if only list_toolsets, describe_toolset and call_tool are advertised, never call an operational name as a top-level tool. Pick a capability with list_toolsets, load only that group with describe_toolset, then invoke it through call_tool(name=..., arguments=...). If the exact tool and arguments are already known, call_tool can dispatch directly.

Principles

• Match the user's request. Do not run setup, discovery or scene analysis by habit, and do not call get_bridge_status or get_session_context as a preamble.
• Prefer a dedicated tool over raw MAXScript whenever one clearly matches.
• Do not render unless the user asks. Viewport capture is fine when visual proof helps.
• Verify meaningful edits with query_scene(action="delta"), re-inspection or a capture.
• Keep mutating calls sequential. Concurrent writes interleave undo transactions: a crash, then persistent corruption such as phantom successes and wrong handles.
• Multiple Max instances: the first native connection stays bound to that Max and never silently switches while it runs. Use list_max_instances, select_max_instance(pid), get_selected_max_instance and release_max_instance. MCP_MAX_PIPE or MCP_MAX_PID pins the startup target (the pipe takes precedence); release also clears it.
• Shared selection: the selection belongs to the MCP server process, so sessions that share one server share it, and one session's select moves the others. Pass expected_pid (every tool takes it) to any call that must reach one particular Max. A mismatch returns TARGET_MISMATCH with nothing sent. selection_generation in each reply's transport changes on every select, release or re-resolve.
• Default target after a restart: a target the server picked by itself (target_source "default" or "claim") follows its Max's restart (the Max that started after it stopped answering), and the reply warns. A Max that was already open belongs to another session and is never taken over: until the restart is up, calls fail with retryable TARGET_UNAVAILABLE and nothing is sent; select_max_instance it to work there. Several new instances: AMBIGUOUS, select one. A claimed instance wins. Explicit and environment targets never move; they fail until you select or release.

Tool Choice

• Scene reads: query_scene (overview/filter/class/property/selection/delta), get_hierarchy, get_instances, get_dependencies, walk_references. resolve_node_refs gives canonical handle/name/path identity. scene_qa checks naming, transforms, hierarchy and timeline only; it never judges meshes or visuals, and its fix repairs naming only (preview with dry_run=true unless approved).
• Inspection: inspect_object, inspect_properties, analyze_node_orientation (before rig, vehicle or camera transforms). For unfamiliar plugin APIs: introspect_class, introspect_instance, discover_plugin_classes, map_class_relationships, inspect_plugin_class. Arnold materials such as ai_standard_surface may be missing from class discovery; use inspect_plugin_class or introspect_osl.
• Edits: object, modifier, material, controller, organization (manage_layers, manage_groups, manage_selection_sets) and viewport tools. Use scene_patch for a preflighted batch of renames, relative transforms, flags or parenting committed as one undo step.
• Fallbacks: execute_maxscript, or execute_python (pymxs, needs safe mode off), only when no dedicated tool exists.
• Scene files: manage_scene (hold/fetch/reset/save/info). inspect_max_file, search_max_files, merge_from_file and batch_file_info work without loading a scene.
• Interactive sessions: watch_scene follows the user's actions.

Workflows

Identity and tokens

• Node handles are stable only within the loaded scene. Cross-check cached handles with name or path, and refresh after a reset or load.
• Pass expected_scene_seq from resolve_node_refs to scene_patch when stale targeting matters; selection changes do not invalidate it.
• Guarded edits take the token from a fresh inspection: expected_mesh, expected_view, curve_token, expected_style, expected_controller, plugin schema/state tokens, expected_dialog. A refused token means inspect again, never bypass the guard.

Modeling

• Polygon edits: inspect_mesh or an AGENT VIEWPORT capture → pick_component with the capture's view_token as expected_view → mesh_edit(expected_mesh=...) → verify with inspect_mesh, geometry_qa or a capture.
• Construction: create_mesh for computed vertex/face arrays; loft_mesh for parameterized section lofts; curve_model, inspect_curve and edit_curve for curve-driven forms (read curve-construction.md first); draw_spline plus Lathe/Extrude/Bevel_Profile/Sweep through add_modifier, refined with spline knot edits or edit_vertices conform.
• Edits act on the editable base cage and preserve modifiers above it. Collapsing (convert=true, collapse_modifier_stack) happens only when requested.
• boolean_operation: prefer inline cutters (named, atomic, no scene litter). Non-live operands are consumed, so never consume a node other tools still reference by name.
• After placing parts that should sit on or join each other, run contact_check and judge reported depth against the design intent.

Materials

• Create and assign: assign_material, create_material_from_textures, smart_import, palette_laydown. They default to OpenPBR; pass material_class for another renderer. Share an existing material with assign_material(names=[...], source_name=...).
• Edit: set_material_property, set_material_properties, set_sub_material, create_texture_map, set_texture_map_properties. Switch pipelines with create_shell_material, replace_material and batch_replace_materials.
• replace_material applies source_material wherever target_material is used. source_from picks where the source is found, e.g. "material_editor" for a re-imported Cosmos copy. On no_match, check the direction before retrying; on blocked, do not swap the arguments.
• Audit: get_material_slots (prefer slot_scope="map"), get_materials, and material_roles (follow next_offset; check complete and truncated).
• OSL: write_osl_shader, then introspect_osl before wiring. The shader name must match shader_name; OSLMap lowercases parameter names.
• material_class is the material's own class name: PhysicalMaterial, not Physical (the camera).

Lighting and plugin settings

• lighting_capabilities → create_lights → inspect_lights → edit_lights. Never infer integer enum meanings. RGB is linear in the rendering color space, Kelvin is explicit, and EXR/HDR inputs get no extra gamma.
• Other plugin settings: inspect_plugin_class or inspect_plugin_instance with schema_version=2, then plugin_patch with the returned schema and state tokens. Shared or animated resources need deliberate handling.

Viewport and capture

• Open agent_viewport(action="open") before inspection captures. Navigation and captures then default to it and never redirect into the user's view; source="active" targets the user's view explicitly. Release and reopen after a scene load.
• set_viewport aims by eye and target without creating a camera. Use capture_viewport, capture_multi_view or capture_screen(enabled=True) for stills and frame-buffer crops.
• capture_multi_view views take names, three_quarter, current or [x, y, z] directions. shading and edges apply to that capture only: clay with edges shows topology. For animation, rigs and simulations, frames or frame_count give one view over time in a single image instead of repeated scrub-and-capture calls.
• Start interactive previews (agent_viewport(action="render")) and production renders (render_automations) only on request. A capture never certifies convergence or finished denoising.

Animation and controllers

• Script controllers: script_controller inspect → validate → apply with expected_controller. A controller that returns zero at every frame has failed; inspect it with sample_frames.
• Other controllers: assign_controller, inspect_controller, inspect_track_view, set_controller_props, add_controller_target. Pass list_wireable_params paths, including their [#Parameters] levels, to wire_params unchanged; get_wired_params and unwire_params read and remove wiring.
• keyframe_tracks: timeline reads or sets frame rate, current frame and range. list inspects keys; parent numKeys is often 0 because keys live on Bezier Float sub-controllers. Retimes need time/times or both from_time and to_time. bake and resample skip list, constraint, expression, script and motion-capture controllers. Use loop, or match with order=hierarchy, for parented rigs. tracks takes exact tokens only: all, position/pos, rotation/rot, scale/scl, transform/tm.
• On animated objects, edit keys with keyframe_tracks; transform_object rewrites keys at the current frame.

Plugins and assets

• tyFlow graph work: read tyflow-graphs.md completely before acting.
• RailClone (7.3.5+): get_railclone_style → edit the XML → set_railclone_style(expected_style=...) → verify with get_railclone_output. Read railclone.md first.
• Data Channel and Max Creation Graph: read procedural-graphs.md completely before acting.
• Forest Pack: scatter_forest_pack, then hide the source meshes.
• Cosmos: cosmos_search → cosmos_download → cosmos_import. Repeating a completed import adds another instance.
• Plugin surfaces: discover_plugin_surface, get_plugin_manifest, and resource://3dsmax-mcp/plugins/{name}/manifest|guide|recipes|gotchas.

Dialogs