Develop

MCP Tools Reference

Updated: Sep 4, 2026

The iwsdk-runtime MCP server exposes 45 public tools in IWSDK 0.5.3. The installed CLI is the authority for descriptions, required fields, accepted values, and limits:

npx iwsdk mcp inspect
npx iwsdk mcp inspect --tool scene_render_file

Your AI tool receives the same schemas through MCP. Prefer the reported schema over remembered parameters.

Tool groups

Group	Count	Purpose
`xr_*`	16	Control XR sessions, tracked poses, input mode, and controller or hand input.
`browser_*`	3	Capture the application runtime, read console logs, and reload the page.
Scene file and Editor	10	Validate, compose, open, inspect, and capture native scene files.
Runtime scene	3	Inspect the live application hierarchy, transforms, and render statistics.
`ui_*`	2	Discover UIKitML assets and render previews.
`ecs_*`	11	Inspect and modify ECS execution and state.

WebXR tools

Tool	Purpose
`xr_get_session_status`	Get XR session and device status.
`xr_accept_session`	Accept an offered XR session.
`xr_end_session`	End the active XR session.
`xr_get_transform`	Read a tracked device’s position and orientation.
`xr_set_transform`	Set a tracked device’s position or orientation.
`xr_look_at`	Orient a device toward a world-space target.
`xr_animate_to`	Animate a device toward a position or orientation.
`xr_set_input_mode`	Switch between controller and hand input.
`xr_set_connected`	Connect or disconnect a controller or hand.
`xr_get_select_value`	Read a trigger or pinch value.
`xr_set_select_value`	Set a trigger or pinch value for held interactions.
`xr_select`	Dispatch a complete select press and release.
`xr_get_gamepad_state`	Read controller buttons and axes.
`xr_set_gamepad_state`	Set controller button or axis values.
`xr_get_device_state`	Read the complete emulated device state.
`xr_set_device_state`	Apply partial device state, or reset it when state is omitted.

Pose and interaction assertions require an active XR session. Check xr_get_session_status and call xr_accept_session when the application is offering a session.

Browser tools

Tool	Purpose
`browser_screenshot`	Capture the application runtime. If Editor is visible, the tool switches to Runtime before capture.
`browser_get_console_logs`	Read logs from the managed application page.
`browser_reload_page`	Reload the managed application page.

browser_screenshot has no target parameter. Use scene_screenshot when you need an Editor image.

Scene file and Editor tools

Native scene files are an agent authoring API. Edit public/scenes/*.iwsdk.scene.json with file tools, then use these MCP tools to validate and inspect the files. MCP does not provide the public scene-document mutation tools found in earlier experimental contracts.

Tool	Purpose
`scene_get_capabilities`	Read the native scene format and editor capabilities. Pass `full: true` for the expanded contract.
`scene_render_file`	Validate and render a detached scene file without changing the active Editor document.
`scene_flatten_file`	Resolve imports and write one import-free scene file.
`scene_open`	Open an existing, import-free scene file in Editor.
`scene_get_state`	Read the active file, selection, hashes, diagnostics, dirty or conflict state, runtime readiness, and render statistics.
`scene_select`	Replace the Editor selection with the supplied `nodeIds` array.
`scene_set_preview_visibility`	Apply preview-only visibility, context, ghosting, locking, solo, or saved-arrangement operations.
`scene_set_camera`	Set a named, stepped, orbit, perspective, or orthographic Editor camera.
`scene_screenshot`	Capture the native scene with explicit camera and size options.
`scene_measure_image_regions`	Measure named regions when you already have a valid `captureToken`.

The current scene version is iwsdk.scene.v1. Node content can be a group, asset, instance, or pattern. Scene resources currently describe prefabs. Asset nodes refer to asset identifiers supplied by the project manifest, including identifiers for procedural Three.js assets.

The public tool set does not include the scene_capture_review operation that issues the trusted captureToken required by scene_measure_image_regions. Do not present region measurement as a runnable end-to-end public workflow unless another supported integration has already supplied a valid, session-bound token.

For imported compositions, always use scene_render_file first, scene_flatten_file second, and scene_open only on the flattened output. Configure the application to load that flat output through iwsdk.config.json. A successful flatten proves sourceRuntimeHash === outputRuntimeHash; it does not imply that source-document, composed-document, and runtime hashes are the same. See Workflows.

Runtime scene tools

Tool	Purpose
`scene_get_render_stats`	Read runtime renderer counters, scene bounds, resource counts, and scene asset, environment, light, and material summaries.
`scene_get_runtime_hierarchy`	Traverse the live application `Object3D` hierarchy.
`scene_get_object_transform`	Read local and global transforms by runtime UUID or native scene node ID.

These tools inspect the running application, not the authored Editor document. scene_get_render_stats returns calls, triangles, points, lines, geometries, textures, programs, meshCount, materialCount, shadowCasters, worldBounds, framingBounds, environment, sceneAssets, sceneEnvironment, sceneLights, and sceneMaterials. Editor-only fields such as objectCount, nodeCount, geometryCount, visibleNodeIds, and frameTimeSamplesMs come from Editor state or capture results, not this runtime tool. scene_get_object_transform also reports the position relative to the XR origin, which can be passed to xr_look_at.

UIKitML tools

Tool	Purpose
`ui_list_assets`	List UIKitML assets available to the project.
`ui_render_preview`	Render a UIKitML preview without inserting it into a scene.

Use these tools for asset discovery and visual preview. Make persistent project changes through the project’s source files.

ECS tools

ECS tools require the IWSDK runtime bridge.

Tool	Purpose
`ecs_pause`	Pause ECS system updates while the render loop continues.
`ecs_resume`	Resume ECS system updates with a capped first-frame delta.
`ecs_step`	Advance a fixed number of ECS frames while paused.
`ecs_query_entity`	Read component data for an entity index.
`ecs_find_entities`	Find entities by components or an object-name pattern.
`ecs_list_systems`	List systems, priorities, pause state, configuration keys, and query counts.
`ecs_list_components`	List registered component schemas.
`ecs_toggle_system`	Pause or resume one system by name.
`ecs_set_component`	Set one component field after inspecting its schema and current value.
`ecs_snapshot`	Store a labeled snapshot of ECS entity and component state.
`ecs_diff`	Compare two labeled snapshots.

Call ecs_pause before ecs_step, and call ecs_resume when deterministic inspection is complete.

Guard against stale browser state

Every public runtime tool accepts the optional expectedTab precondition added by the CLI. Supply the tab identity returned by current state when a sequence must fail instead of acting on a stale or reloaded tab.

Choose the correct evidence surface

Claim	Use this evidence
Native scene layout or framing	`scene_screenshot`, with `captureMode: render` to omit Editor overlays or `captureMode: editor` to include selection and editing overlays
Validation, dirty, conflict, file, or runtime-readiness diagnostics	`scene_get_state`
Application behavior, system-driven motion, or input results	`browser_screenshot` and `browser_get_console_logs`
Live application hierarchy or transform	`scene_get_runtime_hierarchy` and `scene_get_object_transform`
Deterministic ECS state change	`ecs_snapshot`, `ecs_diff`, and targeted entity queries

An Editor screenshot is not proof of runtime behavior, and its pixels are not a substitute for the structured diagnostics from scene_get_state. A runtime screenshot is not a substitute for either source.

Get started with AI

Choose a development mode

Follow common workflows