Develop

Getting started with Meta XR Operator

Updated: Sep 9, 2026
Experimental feature
Meta XR Operator is an experimental component of the Meta XR Core SDK. Tool names, APIs, and behavior may change in future releases. Avoid depending on it in production apps.
This guide walks you through setting up Meta XR Operator in a Unity project: install the Meta XR Core SDK, set up the Meta XR Operator OpenXR API layer and MCP proxy from the AI Tools panel, and connect an AI coding agent to your running app. By the end, you can ask an agent a question such as “What is the current XR session state?” and have it answer from your live app.
The fastest way to iterate is in the Unity Editor with Meta XR Simulator, so this guide targets the desktop Editor workflow. To run on a headset instead, finish this guide and then see Using with Meta Quest.
Not using Unity? See Connecting AI agents (standalone) for the standalone setup.

Before you begin

Make sure you have:
  • Unity 6000.0.x or later.
  • Meta XR Core SDK v207 or later.
  • OpenXR Plugin (com.unity.xr.openxr) 1.17.0 or later.
  • An MCP-compatible AI coding agent.
  • On Windows, Quest Link or Meta XR Simulator. On macOS (Apple Silicon), Meta XR Simulator.
For a full description of the feature and what agents can do with it, see the Meta XR Operator overview.

Step 1: Install the Meta XR Core SDK

Meta XR Operator ships as an optional, experimental component of the Meta XR Core SDK. Install or upgrade to v207 or later.
  1. Follow the Meta XR Core SDK setup guide to add the SDK to your project, and select version v207 or later.
  2. Open Window > Package Manager and confirm that OpenXR Plugin (com.unity.xr.openxr) is installed at 1.17.0 or later. If it isn’t listed, install it by name from the Unity Registry.
  3. In Project Settings > XR Plug-in Management, enable OpenXR for the platforms you build for (your desktop platform for Editor play, and Android for Meta Quest).
Package Manager showing the Meta XR Core SDK and OpenXR Plugin versions

Step 2: Set up Meta XR Operator from the AI Tools panel

The Meta XR Core SDK includes an AI Tools panel that guides you through the setup process of Meta XR Operator, such as installing the Meta VR CLI and the Meta XR Operator tool, registering the MCP server with your AI coding agent, and activating the OpenXR API layer.
  1. In the Meta XR SDK Window, select AI Tools. If the window isn’t visible, select Window > Meta > Meta XR SDK to open it.
    In Unity 6000.3 or later, you can pin the SDK menu to the toolbar. Right-click the Unity toolbar and select Meta XR SDK > SDK menu.
  2. Under Select your service provider, choose your AI coding agent.
  3. Under Install and set up AI tools, in the XR Operator card, click Install Meta VR CLI (or Install XR Operator if Meta VR CLI is already installed). Installing Meta VR CLI from here will also automatically install Meta XR Operator at the same time.
  4. In the same AI Tools window, click Run Command to run the generated command to install Meta VR CLI for your respective coding agent. Wait until the status shows Connection verified, then click Activate XR Operator. The status changes to XR Operator is activated.
  5. Under Install project-level skills, click the skills installation button for your agent so it has Meta XR Operator workflow guidance when you launch it from your project folder.
The AI Tools panel showing the completed setup
Windows Firewall (optional)
The panel’s Configure Windows Firewall step lets a Meta Quest headset reach the AI Tools servers running in the Editor. You don’t need it for the local desktop workflow with the MCP proxy.

Step 3: Configure your project with the Project Setup Tool

On Windows, use the Project Setup Tool to apply the remaining project settings that Meta XR Operator needs.
  1. In the Meta XR SDK Window, select Project Setup Tool. If the window isn’t visible, select Window > Meta > Meta XR SDK to open it.
  2. Review the Meta XR Operator rules and apply the recommended fixes. This upgrades the OpenXR Plugin to 1.17.0 or later, enables the API Layers feature, and registers the Meta XR Operator layer for you.
macOS
On macOS, the AI Tools panel enables the layer through environment variables when you enter Play mode, rather than adding it to the visible API Layers list, so there’s no manual layer registration to do.
Register the API layer manually (optional)
If you’d rather wire the layer yourself, go to Project Settings > XR Plug-in Management > OpenXR, enable the API Layers feature, click its settings (gear) icon, click +, choose x64 (Windows), and add the Meta XR Operator layer manifest from the Core SDK. On Meta Quest builds the layer is bundled into the app automatically, so there’s no layer to add here. See OpenXR plugin settings for more.

Step 4: Connect your AI agent

The Run Command step in the AI Tools panel is the primary setup flow. It registers the MCP proxy with your selected agent. The agent is connected once the panel shows Connection verified.
For optional manual setup, register the server yourself with the Meta VR CLI by running metavr mcp install <agent> (for example, metavr mcp install claude-code). Then check your agent’s MCP server status and confirm that the metavr server is connected.
Note that the AI Tools panel automatically installs Meta VR CLI and Meta XR Operator for you. For optional manual setup, follow the Install Meta VR CLI instructions to set up Meta VR CLI, then run metavr tools install xroperator (or metavr tools update xroperator to upgrade it).
Verify with MCP Inspector
Prefer a quick manual check? Run the MCP Inspector⁠ with npx @modelcontextprotocol/inspector@0.17.2 (requires Node.js). Set Transport Type to SSE, URL to http://localhost:8720/sse, and Connection Type to Direct, then click Connect and open the Tools panel to list every tool Meta XR Operator exposes.

Step 5: Test the connection

Testing on a Meta Quest headset? See Using with Meta Quest.
To test the connection using Meta XR Simulator:
  1. Launch your AI agent from your Unity project root (the folder that contains Assets, one level above it) so it picks up the Meta XR Operator skills you installed in Step 2.
  2. Open a sample scene, or any OpenXR scene in your project.
  3. Enter Play mode. If you use Meta XR Simulator, the Simulator window opens and your app runs in XR. If the Simulator isn’t working, see Using with Meta XR Simulator.
  4. In your AI agent, ask a question that reads live state, such as “What is the current XR session state?”
The agent calls Meta XR Operator and reports details such as the session handle and state (for example, FOCUSED), which confirms the end-to-end connection. From here, you can ask the agent to read head and controller poses, set controller input, capture composited images, or list spatial entities in the scene.
The agent can reach your app only while it runs in Play mode (or while it runs on a connected headset). When you exit Play mode, the live tools become unavailable until you re-enter it.

Troubleshooting quick reference

SymptomTry this
The agent’s MCP server status shows the metavr server as not connected, or the agent can’t reach the MCP server
Re-run the XR Operator setup steps in the AI Tools panel (Install XR Operator, then let it re-register with your agent). See the Meta VR CLI documentation for more details.
The agent connects but live tools return no data, such as “no active session”
Enter Play mode in the Editor, or launch the app on a connected headset, so there’s a live XR session to read.
General setup issues, or API layer isn’t applied
In the Meta XR SDK Window, select Project Setup Tool. If the window isn’t visible, select Window > Meta > Meta XR SDK to open it. Fix all Meta XR Operator warnings and errors.
Port 8720 already in use
Close other running XR apps or MCP server instances, then start your app again.
The API Layers feature isn’t visible in OpenXR settings
Update the OpenXR Plugin to 1.17.0 or later.
Custom tools don’t appear
Register them during Start() rather than Awake().
For platform-specific issues, see Using with Meta XR Simulator and Using with Meta Quest.

What’s next

Meta
English (US)
© 2026 Meta