Develop

Getting started with Meta XR Operator

Updated: Jul 23, 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.

Before you begin

Make sure you have:

Unity 6000.0.x or later.

Meta XR Core SDK v205 or later.

OpenXR Plugin (com.unity.xr.openxr) 1.17.0 or later.

An MCP-compatible AI coding tool, such as Claude Code.

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 v205 or later.

Follow the Meta XR Core SDK setup guide to add the SDK to your project, and select version v205 or later.

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.

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

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 MCP proxy, connecting it to your AI coding assistant, and activating the OpenXR API layer.

From the Unity menu bar, open Meta > Tools > AI Tools. You can also open it from the Status Menu.

Under Select your service provider, choose your AI coding assistant, such as Claude Code. The install command shown in the panel is tailored to your choice.

Under Install and set up AI tools, in the XR Operator card, click Install MCP Proxy, then click Run Command to run the generated command (or copy it and run it yourself). Wait until the status shows Connection verified, then click Activate XR Operator. The status changes to XR Operator is activated.

Under Install project-level skills, click the Install ... skills in project button for your assistant (for example, Install Claude Code skills in project) so your agent has Meta XR Operator workflow guidance when you launch it from your project folder.

The AI Tools panel showing the connection verified

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.

Open Edit > Project Settings > Meta XR.

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.

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 already registers the MCP proxy with your selected agent, so your agent is connected once the status shows Connection verified.

To register the proxy manually instead, point your agent at the proxy binary the panel installed under %USERPROFILE%\meta-xr-operator\. For Claude Code:

claude mcp add meta-xr-operator -- <path to meta-xr-operator-mcp-proxy.exe>
claude mcp list

A successful connection looks like this:

meta-xr-operator: ... - ✓ Connected

To remove the server later, run claude mcp remove meta-xr-operator.

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

To test the connection using Meta XR Simulator:

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.

Open a sample scene, or any OpenXR scene in your project.

Enter Play mode. If you use Meta XR Simulator, the Simulator window opens and your app runs in XR.

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

Symptom	Try this
`claude mcp list` shows the server as not connected, or the agent can’t reach the MCP server	Reinstall the proxy from the AI Tools panel (Install MCP Proxy, then Run Command) and wait for Connection verified.
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	Open the Project Setup Tool (Edit > Project Settings > Meta XR) and 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()`.