Develop

MCP Tools Reference

Updated: Nov 2, 2026
The iwsdk-runtime MCP server exposes the public tools described on this page. The installed CLI is the authority for the current tool list, 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

GroupPurpose
xr_*
Control XR sessions, tracked poses, input mode, controller input, and emulated hand interactions.
browser_*
Capture, inspect, and interact with the current application, profile the host browser, read diagnostics, reload the page, and mute the tab.
Scene file and Editor
Validate, compose, open, inspect, and capture native scene files.
Runtime scene
Inspect the live application hierarchy, transforms, and render statistics.
asset_render_preview
Render one model asset in isolation.
ui_*
Discover UIKitML assets, render previews, and inspect live panels.
ecs_*
Inspect and modify ECS execution and state.

WebXR tools

ToolPurpose
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.
Positions and orientations are relative to the XR origin (world.player). -Z is forward and +Y is up. See XR origin.

Hand tools

ToolPurpose
xr_run_sequence
Run a complete hand interaction, such as a press, pinch-grab, carry, set-down, or gesture, in one call.
xr_cancel_sequence
Stop a running sequence.
xr_list_targets
List the target names that xr_run_sequence steps accept, with each target’s box center and size.
xr_set_hand_pose
Shape a hand with a built-in IWER pose such as point, fist, or thumbs-up, optionally per finger and faded over duration.
xr_get_hand_state
Read the pose, pinch, and XR-origin positions of the wrist, grip, grasp point, and fingertips.
xr_microgesture
Swipe or tap the thumb along the index finger. The application sees the hand gamepad’s microgesture buttons.
Call xr_set_input_mode with hand first. These tools come from IWER and drive the emulated hands the way a person moves them, so your application’s real poke, pinch, and grab code reacts.

Run a hand sequence

xr_run_sequence performs each move as one smooth reach. The head turns toward the target, and the body leans or steps closer when the target is out of reach. The result lists the select events the application saw, step times, press contact times, warnings, and the final hand state.
  • Pass dryRun: true to check a plan without moving anything.
  • A sequence gives up 28 seconds after it is sent and returns a partial result. Call xr_cancel_sequence to stop it sooner.
  • A UIKit click needs the fingertip to leave within 800 ms. Slow headless frames can stretch a press past that, so press again when presses[0].contactMs is 800 or more.
npx @iwsdk/cli xr run-sequence --input-json \
  '{"device":"hand-right","steps":[{"target":"counter-button","press":{}}]}'

Find hand targets

xr_list_targets resolves target names in the live scene:
  • Entities with PokeInteractable, RayInteractable, OneHandGrabbable, TwoHandsGrabbable, or DistanceGrabbable, by Object3D name, such as Map Pin 1.
  • UIKitML elements with an id inside those entities, such as counter-button. Hidden elements are left out.
A step’s target also accepts a scene node ID, any Object3D name, or a UUID. Targets that share a name are listed under their scene node ID. A press goes to the face toward the body, or to a named face such as { "name": ..., "face": "top" }. A grab goes to the middle of the object, and setting a held object down goes to the top of the target.

Pose and place a hand

Poses never select. Pinch with xr_set_select_value or a sequence step’s pinch.
xr_set_transform and xr_animate_to also place a hand by a point on it (anchor: index-tip, grasp, or wrist) and orient it by direction ({"fingers":"forward", "thumb":"up"}) or "auto".
xr_set_hand_pose, xr_set_select_value, xr_animate_to, and xr_select reply after their duration has passed, so their default timeout grows by that duration.
Note: On a physical device, IWER places the hands relative to the native session, while IWSDK reports targets relative to world.player. The two agree in the emulator, but targeted sequences have not been verified on a physical device. Check one press on the device before you rely on target names.

Browser tools

The browser group contains seven tools. Each tool targets the current application automatically, whether it is the top-level page or the runtime frame inside the managed workspace. There is no target selector, and these tools do not navigate to arbitrary URLs.
ToolPurpose
browser_screenshot
Capture the current application and return the local image path as screenshotPath.
browser_snapshot
List the current application’s interactive elements, useful text, and canvas regions with refs.
browser_interact
Run a batch of one to ten Playwright actions against the current application.
browser_profile
Start, check, or stop a desktop-browser performance profile.
browser_get_console_logs
Read console calls and other structured browser diagnostics.
browser_reload_page
Reload only the current application surface.
browser_set_muted
Turn all audio in the managed browser tab off or back on.
browser_screenshot has no target parameter. Use scene_screenshot when you need an Editor image.
The seven browser tools operate through IWSDK’s Playwright owner and remain available for browser-first applications without an IWER runtime bridge. XR, ECS, and other runtime-dispatched tools still require their in-page bridge.

Capture screenshots

browser_screenshot writes the image to a local temporary file and returns its path as screenshotPath, without inline base64 data. Optional parameters select png or jpeg, set JPEG quality from 20 to 100, capture the full document, or capture one element by a ref returned from browser_snapshot.
Results include the application identity and URL, whether the application is workspace-framed, image dimensions and MIME type, and whether an oversized capture was downscaled to the configured screenshot bounds.

Inspect the page

browser_snapshot returns a bounded, accessibility-first list. Each element includes a ref, role, name, text, visibility, state, and visible bounds. The result also includes a snapshot ID, application identity, and a truncated flag.
ParameterTypeRequiredDescription
maxNodes
integer
No
1–1000 elements; defaults to 200
maxTextLength
integer
No
16–1000 characters per name or text field
rootRef
string
No
Restrict the snapshot to an existing element ref
Refs are tied to the current application identity and generation. Capture a fresh snapshot after a reload or when an interaction reports a stale ref.

Interact with the page

Prefer snapshot refs with browser_interact. Semantic locators can identify an element by testId, role and optional name, or exact text. Page coordinates are available for 2D input. Add canvasRef to make coordinates relative to a canvas.
Supported actions are click, doubleClick, hover, pointerMove, pointerDown, pointerUp, wheel, fill, type, clear, press, check, uncheck, select, scroll, drag, keyDown, keyUp, and wait. Keyboard actions target the current application, including its runtime frame in the managed workspace.
press is atomic. To hold a key for frame-sampled controls, keep keyDown, a duration-only wait, and keyUp in the same batch:
{
  "steps": [
    { "action": "keyDown", "key": "KeyW" },
    { "action": "wait", "durationMs": 500 },
    { "action": "keyUp", "key": "KeyW" }
  ]
}
Held keys cannot span batches. IWSDK releases any unmatched keys when the batch succeeds or fails. A duration wait accepts durationMs from 0 through 12,000, must fit the remaining batch budget, and cannot be combined with state, text, path, or loadState.
Batch and per-step timeouts are capped at 12,000 milliseconds, and the batch defaults to 10,000. A condition-based wait step can wait for element state, load state, or an expected application path. It does not start navigation.
The result lists completed steps and their durations. On failure, it identifies the failed step, reports whether a retry is appropriate, suggests recovery, and attempts to return a fresh snapshot and PNG screenshot. MCP returns that screenshot as an image content block. The equivalent CLI command writes it to a temporary file and returns the path.

Handle busy and timed-out commands

Browser operations have a 60-second transport budget. They can spend up to 15 seconds waiting behind another browser command, then receive a fresh 27-second active budget. These coordinator failures are retryable:
  • browser_command_busy: The command queue is full.
  • browser_command_queue_timeout: The request expired while waiting, and the browser was left running.
  • browser_command_timeout: The active operation exceeded its budget, so IWSDK closed the managed browser and relaunches it lazily.
  • browser_command_aborted: Queued work was cleared after another active operation timed out. Retry it against the relaunched browser.

Profile the host browser

browser_profile starts, inspects, or stops a bounded desktop-browser performance profile for the current application:
ParameterTypeRequiredDescription
action
string
Yes
start, status, or stop
mode
string
No
interaction, rendering, or trace when starting
maxDurationMs
integer
No
1,000–60,000; defaults to 30,000 and auto-stops safely
profileId
string
No
Require this active profile when stopping
Stopped profiles summarize browser metrics, event timing, requestAnimationFrame intervals, long tasks, and interaction marks.
  • interaction mode includes event-timing observations alongside frame timing.
  • rendering mode omits event timing and concentrates on frame and long-task behavior.
  • trace mode adds a bounded Playwright trace artifact under .iwsdk/artifacts/browser/ to the interaction-oriented measurements.
The result’s summary.collection fields state which collectors ran. Profiles are uncalibrated host-browser diagnostics, not measurements for a target device. Results report classification: "host-browser-diagnostic", calibrated: false, and targetDevice: null.

Read browser diagnostics

browser_get_console_logs accepts optional count, level, pattern, and since filters. Returned diagnostics can include console calls, uncaught page errors, failed requests, dialogs, downloads, popups, and frame navigation.
Entries carry structured context where available, including serialized arguments, source URLs, frame URLs, line, column, HTTP method, resource type, failure text, and a repeat count for compacted duplicates. Results default to the 100 most recent matching entries, cap count at 200, and enforce a bounded response size.
browser_reload_page returns the reloaded application URL, page ID, and tab generation.

Mute the managed browser

The managed browser’s app-mode window hides Chromium’s own tab mute control. browser_set_muted and the speaker button in the Runtime and Editor bar of the workspace share one dev-session state:
ParameterTypeRequiredDescription
muted
boolean
Yes
true mutes the tab; false turns its audio back on
Muting covers Web Audio output and media elements in every frame, including the runtime frame and the Editor. Applications keep running: audio contexts keep their state and clock, and an element’s muted property still reports the value page code set.
The state persists across reloads and managed-browser relaunches for the dev session, and runtime_get_status reports it as browser.audioMuted. Two rare cases are not covered: media that plays automatically inside a declarative shadow root, and a detached media element that automatically plays a srcObject stream. The result is { "muted": <boolean> }. The equivalent CLI command is iwsdk browser set-muted --muted <true|false>.

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

Scene paths and output files

  • scene_open requires an existing file under public/scenes/ that ends in .iwsdk.scene.json. Symbolic links are resolved first: a link can point to another file under public/scenes/, but not outside it, and public/scenes/ itself must resolve inside the project. Opening changes the active document and reconnects the editor session. It never creates a file.
  • scene_render_file accepts path and the optional view (a canonical view such as front, top, or quarter), viewId (an exact saved authoring view), width, and height. A valid result includes source, composed, and runtime hashes, resolved dependencies, camera metadata, render metadata, screenshotSha256, and a local screenshotPath. An invalid result includes structured diagnostics and no screenshot.
  • scene_flatten_file refuses sources, imports, and output outside public/scenes/ after resolving symbolic links. When you omit outputPath, it writes <source>.flat.iwsdk.scene.json. It refuses to replace an existing destination, including in-place output, unless overwrite is true.
  • scene_screenshot writes the PNG to a local temporary file and returns screenshotPath with the active file, hashes, camera, renderer environment, visible node IDs, validation diagnostics, and render statistics.
Scene tools do not embed image bytes in MCP responses.

Runtime scene tools

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

Scene environment fields

sceneEnvironment.background reports what is behind the scene, or null when none of these types applies:
typeFields
dome-gradient
sky, equator, ground (authored arrays), intensity, elevationDeg, azimuthDeg, dither
dome-texture
src, intensity, blurriness, rotation
gradient
topColor, bottomColor, exponent: a background texture with the older scene gradient marker
color
color
transparent
None: no background and clear alpha 0, as in an AR session
sceneEnvironment.imageBasedLighting is { type: 'ibl-gradient', sky, equator, ground, intensity }, { type: 'ibl-texture', src, intensity, rotation }, { type: 'room', intensity, sigma, texture } for an environment texture with the older room IBL marker, or null. An IBLTexture with src: 'room' reports ibl-texture. A DomeGradient is hidden during AR passthrough, so an AR session reports transparent even when the level root has one.
sceneEnvironment.domeFades lists every node with a DomeFade, sorted by nodeId, with start, end, meshCount, skippedMaterials, active, and inactiveReason (no-dome-gradient, dome-texture-active, ar-session, no-meshes, or null while it fades).
sceneEnvironment.groundShadows is { contactShadows, shadowCatchers }, the number of ContactShadow and ShadowCatcher meshes in the scene. Both are runtime-only meshes, so framingBounds and sceneAssets[].meshCount leave them out, while worldBounds and the total meshCount include them.

Model inspection tools

asset_render_preview renders one glTF or procedural manifest asset in isolation without modifying the open scene. The result persists one labeled contact sheet to screenshotPath and returns geometry diagnostics without embedding image bytes. Use ui_render_preview for UIKitML assets.
ParameterTypeRequiredDefaultMinimumMaximumDescription
assetId
string
Yes
-
-
-
Manifest id of the model
views
string[]
No
5 views
1
6
Ordered canonical views
mode
string
No
material
-
-
material or neutral clay
focus
string
No
-
-
512
Exact named part or named hierarchy path
width
number
No
640
320
2048
Composite width in pixels
height
number
No
480
240
2048
Composite height in pixels
background
string
No
#202226
-
-
Three.js-compatible background color
Diagnostics include raw and framing bounds, object, mesh, geometry, and material counts, rendered triangles, and warnings for malformed geometry or weak inspection identity. To keep model context bounded, MCP responses include at most 40 named part paths, without their bounds, plus the total named-part count. CLI JSON output keeps the complete named-part bounds.
Transparent and additive effects remain visible but do not control automatic camera framing. Use focus after the contact sheet exposes a suspicious part. The full asset remains rendered so attachment context is preserved.

UIKitML tools

ToolPurpose
ui_list_assets
List UIKitML assets available to the project.
ui_render_preview
Render a UIKitML preview without inserting it into a scene.
ui_inspect
Inspect the live UIKitML document of one panel entity in the running application.
Use ui_list_assets and ui_render_preview for asset discovery and visual preview. Make persistent project changes through the project’s source files. Use ui_inspect for the current state of a panel in the running application.

Inspect a live panel

Find the panel entity first with ecs_find_entities or iwsdk scene runtime-hierarchy, then pass its entity index to ui_inspect. For manifest-backed panels, search by the authored panel namePattern. The PanelDocument component identifies legacy PanelUI entities only.
Omit selector to list every element with a stable ID in document order, or narrow the result with an existing UIKit selector: #id, .class, or descendant combinations of those selectors, up to 16 selector parts.
ParameterTypeRequiredDefaultMaximumDescription
entityIndex
integer
Yes
-
-
ECS entity that owns the live panel
selector
string
No
all stable IDs
512 chars, 16 parts
UIKit ID, class, or descendant selector
properties
string[]
No
common live state
20
Computed UIKit property names to include
limit
integer
No
50
50
Maximum matching elements
The result includes panel identity and bounded element summaries containing IDs, classes, current text, visibility, interaction state, layout size, layout center, and the requested computed properties. ui_inspect only observes. It does not click or change the UI. UIKit descendants remain UIKit components rather than synthetic ECS entities. Inspection traverses at most 10,000 objects, and oversized documents fail with an error.
npx @iwsdk/cli ui inspect --input-json \
  '{"entityIndex":14,"selector":"#counter-button"}'

ECS tools

ECS tools require the IWSDK runtime bridge.
ToolPurpose
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.
ecs_snapshot retains two labels by default. Pass capacity from 2 through 20 to configure a larger rolling window for the current runtime. Its result lists the active capacity, stored labels, and any label evicted by that capture.
ecs_set_component edits to DomeGradient and IBLGradient apply on the next frame. DomeTexture and IBLTexture apply an edit only once _needsUpdate is set to true, so include it in the same call.

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

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