Develop

MCP Tools Reference

Updated: Jul 22, 2026

The IWSDK MCP server exposes 32 tools organized into 9 categories. These tools give AI agents full control over the emulated XR runtime, the browser, the Three.js scene, and the ECS simulation.

Run the parity tests that match the changed surface:

pnpm test:cli-mcp-parity
pnpm test:reference-cli-mcp-parity
pnpm test:mcp-parity

Use test:cli-mcp-parity for runtime tool contracts or CLI mappings. Use test:reference-cli-mcp-parity for @iwsdk/reference mappings. Use test:mcp-parity when a change touches both surfaces or before a full contract review.

Session Management

`xr_get_session_status`

Get the current XR session and device status. The response also includes managed-browser readiness metadata so agents can distinguish “runtime up but browser still connecting” from “browser connected”.

Parameters: None

`xr_accept_session`

Accept an offered XR session — equivalent to clicking the “Enter XR” button.

Parameters: None

`xr_end_session`

End the current active XR session.

Parameters: None

Transform Control

`xr_get_transform`

Get the position and orientation of a tracked device.

Parameter	Type	Required	Description
`device`	`string`	Yes	`headset`, `controller-left`, `controller-right`, `hand-left`, `hand-right`

`xr_set_transform`

Set the position and/or orientation of a tracked device. Position is in meters, and orientation can be a quaternion or Euler angles in degrees.

Parameter	Type	Required	Description
`device`	`string`	Yes	Device to move
`position`	`{x, y, z}`	No	World position in meters. Y=1.6 is standing height.
`orientation`	`{x,y,z,w}` or `{pitch,yaw,roll}`	No	Quaternion or Euler angles (degrees)

`xr_look_at`

Orient a device to look at a specific world position.

Parameter	Type	Required	Description
`device`	`string`	Yes	Device to orient
`target`	`{x, y, z}`	Yes	World position to look at
`moveToDistance`	`number`	No	Also move the device to this distance from the target

`xr_animate_to`

Smoothly animate a device to a new position and/or orientation over time.

Parameter	Type	Required	Description
`device`	`string`	Yes	Device to animate
`position`	`{x, y, z}`	No	Target world position in meters
`orientation`	`{x,y,z,w}` or `{pitch,yaw,roll}`	No	Target rotation
`duration`	`number`	No	Animation duration in seconds (default: 0.5)

Input Mode

`xr_set_input_mode`

Switch between controller and hand tracking input modes.

Parameter	Type	Required	Description
`mode`	`string`	Yes	`controller` or `hand`

`xr_set_connected`

Connect or disconnect an input device.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left`, `controller-right`, `hand-left`, `hand-right`
`connected`	`boolean`	Yes	Whether the device should be connected

Select / Trigger

`xr_get_select_value`

Get the current select (trigger/pinch) value for an input device.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left`, `controller-right`, `hand-left`, `hand-right`

`xr_set_select_value`

Set the select (trigger/pinch) value. Use for grab-move-release patterns: set to 1.0 to grab, move the controller, then set to 0.0 to release.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left`, `controller-right`, `hand-left`, `hand-right`
`value`	`number`	Yes	0 (released) to 1 (fully pressed/pinched)

`xr_select`

Perform a complete select action (press and release). Dispatches selectstart, select, and selectend events.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left`, `controller-right`, `hand-left`, `hand-right`
`duration`	`number`	No	How long to hold in seconds (default: 0.15)

Gamepad

Controllers only — not available for hand tracking.

`xr_get_gamepad_state`

Get the full gamepad state including all buttons and axes.

Button indices: 0=trigger, 1=squeeze, 2=thumbstick press, 3=A/X, 4=B/Y, 5=thumbrest.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left` or `controller-right`

`xr_set_gamepad_state`

Set gamepad button and axis values by index.

Parameter	Type	Required	Description
`device`	`string`	Yes	`controller-left` or `controller-right`
`buttons`	`[{index, value, touched?}]`	No	Button states to set
`axes`	`[{index, value}]`	No	Axis values to set (0=thumbstick X, 1=thumbstick Y)

Device State

`xr_get_device_state`

Get comprehensive state of the XR device including headset position, controller/hand transforms, input mode, FOV, and stereo settings.

Parameters: None

`xr_set_device_state`

Set device state. When called with no state parameter, resets everything to defaults.

Parameter	Type	Required	Description
`state`	`object`	No	Partial device state with `headset`, `inputMode`, `stereoEnabled`, `fov`, `controllers`, `hands`

Browser

`browser_screenshot`

Capture a screenshot of the browser. Returns the image as inline base64 PNG.

Parameters: None

`browser_get_console_logs`

Get console logs from the browser with optional filtering. Excludes debug level by default.

Parameter	Type	Required	Description
`count`	`number`	No	Maximum number of logs to return (most recent N)
`level`	`string` or `string[]`	No	Filter by level: `log`, `info`, `warn`, `error`, `debug`
`pattern`	`string`	No	Regex pattern to filter log messages
`since`	`number`	No	Return logs since this timestamp (ms since epoch)

`browser_reload_page`

Reload the browser page to reset application state.

Parameters: None

Scene Inspection

These tools require IWSDK MCPRuntime (automatically available in IWSDK projects).

`scene_get_hierarchy`

Get the Three.js scene hierarchy as a JSON tree. Returns object names, UUIDs, types, and entity indices where available.

Parameter	Type	Required	Description
`parentId`	`string`	No	UUID of parent Object3D to start from (defaults to scene root)
`maxDepth`	`number`	No	Maximum depth to traverse (default: 5)

`scene_get_object_transform`

Get local and global transforms of an Object3D. Includes positionRelativeToXROrigin which can be used directly with xr_look_at.

Parameter	Type	Required	Description
`uuid`	`string`	Yes	UUID of the Object3D (from `scene_get_hierarchy`)

ECS Debugging

These tools require IWSDK MCPRuntime.

`ecs_pause`

Pause ECS system updates. The render loop continues (XR session stays alive, screenshots still work) but no systems tick.

Parameters: None

`ecs_resume`

Resume ECS system updates after pausing. The first frame uses a capped delta to avoid physics explosions.

Parameters: None

`ecs_step`

Advance N ECS frames with a fixed time step while paused. Must call ecs_pause first.

Parameter	Type	Required	Description
`count`	`number`	No	Number of frames to advance (1-120, default: 1)
`delta`	`number`	No	Fixed time step in seconds (default: 1/72, matching Quest refresh rate)

`ecs_query_entity`

Get all component data for an entity.

Parameter	Type	Required	Description
`entityIndex`	`number`	Yes	Entity index (from `scene_get_hierarchy` or `ecs_find_entities`)
`components`	`string[]`	No	Specific component IDs to include (defaults to all)

`ecs_find_entities`

Find entities by component composition and/or name.

Parameter	Type	Required	Description
`withComponents`	`string[]`	No	Component IDs entities must have (AND logic)
`withoutComponents`	`string[]`	No	Component IDs entities must NOT have
`namePattern`	`string`	No	Regex to match against entity Object3D name
`limit`	`number`	No	Maximum results (1-50, default: 50)

`ecs_list_systems`

List all registered ECS systems with name, priority, pause state, config keys, and query entity counts.

Parameters: None

`ecs_list_components`

List all registered ECS components with their field schemas (type and default value).

Parameters: None

`ecs_toggle_system`

Pause or resume a specific ECS system by name.

Parameter	Type	Required	Description
`name`	`string`	Yes	System class name (for example, `OrbSystem`)
`paused`	`boolean`	No	`true` to pause, `false` to resume. Omit to toggle.

`ecs_set_component`

Set a component field value on an entity.

Parameter	Type	Required	Description
`entityIndex`	`number`	Yes	Entity index
`componentId`	`string`	Yes	Component ID (for example, `Orb`, `Transform`)
`field`	`string`	Yes	Field name within the component
`value`	`any`	Yes	New value. Scalars: number/string/boolean. Vectors: array (for example, `[1,2,3]` for Vec3).