Develop

Connecting AI agents to Meta XR Operator standalone

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

Meta XR Operator not only ships within the Meta XR Core SDK for Unity, but also as a standalone distribution of prebuilt binaries, so you can use it with any OpenXR app without Unity. This guide covers pointing the OpenXR loader at the API layer, launching your app, and connecting an AI agent through the MCP proxy using the standalone distribution without requiring a Unity project.

Using Unity? Use the AI Tools panel instead

If your app is being launched from a Unity project, don’t follow the manual steps on this page. Use the AI Tools panel and Project Setup Tool instead, which install the proxy, register the API layer, and configure your project for you. See Getting started for more information. The manual environment variables below (XR_API_LAYER_PATH and XR_ENABLE_API_LAYERS) also conflict with Unity, which sets these itself and overrides your values.

Before you begin

Make sure you have:

Download the Meta XR Operator Standalone package. It contains the API layer and the meta-xr-operator-mcp-proxy binary for Windows and macOS.

An OpenXR app to drive, running against Meta XR Simulator or a connected headset.

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

PC quickstart (Windows and macOS)

1. Point the OpenXR loader at the API layer

Set two environment variables so the OpenXR loader finds and enables the layer. Use the folder for your operating system:

# Windows (PowerShell)
$env:XR_API_LAYER_PATH = "C:\path\to\meta-xr-operator-standalone\windows"
$env:XR_ENABLE_API_LAYERS = "XR_APILAYER_METAX_operator"

# macOS
export XR_API_LAYER_PATH=/path/to/meta-xr-operator-standalone/macos
export XR_ENABLE_API_LAYERS=XR_APILAYER_METAX_operator

The layer name, XR_APILAYER_METAX_operator, is the name field in the .json manifest.

2. Launch your OpenXR app

Start your app from the same environment so it inherits the variables. On launch, Meta XR Operator starts its local MCP server inside the app’s process on port 8720.

3. Register the MCP proxy with your agent

Point your agent at the meta-xr-operator-mcp-proxy binary from the bundle. For Claude Code:

# Windows
claude mcp add meta-xr-operator -- C:\path\to\meta-xr-operator-standalone\windows\meta-xr-operator-mcp-proxy.exe

# macOS
claude mcp add meta-xr-operator -- /path/to/meta-xr-operator-standalone/macos/meta-xr-operator-mcp-proxy

Verify with claude mcp list (the server should show as connected), then ask your agent about the running app, for example “What is the current XR session state?”

macOS

If Gatekeeper blocks the proxy or the layer, allow them under System Settings > Privacy and Security.

Meta Quest (standalone)

To run on a Meta Quest headset without Unity, bundle the API layer into your own Android OpenXR app, then forward the port and connect as you would on desktop.

Copy libXrApiLayer_METAX_operator*.so from the bundle’s android/ folder into your APK’s lib/arm64-v8a/ directory.

Copy XrApiLayer_METAX_operator*.json from the bundle’s android/ folder into your APK’s assets/openxr/1/api_layers/implicit.d/ directory.

Add the INTERNET permission to your AndroidManifest.xml (the MCP server needs it): <uses-permission android:name="android.permission.INTERNET" />.

Also in your AndroidManifest.xml, declare the experimental-features manifest entry to unlock the controller automation tools: <uses-feature android:name="com.oculus.experimental.enabled" android:required="false" />.

Build and install your app on the headset, turn on experimental features at runtime via setprop, and then forward the on-device port to your computer:

adb shell setprop debug.oculus.experimentalEnabled 1
adb forward tcp:8720 tcp:8720

For shared on-device setup, such as testing with the headset off your face, and screen-capture permissions, see Using with Meta Quest.

Verify the connection (optional)

To confirm the endpoint is reachable independently of any specific tool, use the MCP Inspector⁠ (requires Node.js):

npx @modelcontextprotocol/inspector@0.17.2

In the browser UI, set Transport Type to SSE, URL to http://localhost:8720/sse, and Connection Type to Direct, then click Connect. Open the Tools panel and click List Tools to see every tool Meta XR Operator exposes.

Advanced: connect directly over SSE

Registering the proxy is the recommended path because it keeps the tool list visible to your agent even when your app isn’t running and reconnects on its own. If your tool supports SSE transport, it can connect directly to http://localhost:8720/sse instead, but it loses the proxy’s offline tool list and automatic reconnect.

Troubleshooting

Symptom	Try this
The agent shows the server as not connected	Confirm you launched the app from the same environment where you set `XR_API_LAYER_PATH` and `XR_ENABLE_API_LAYERS`, and that the proxy path in your `claude mcp add` command is correct.
Connected, but tools return no data	Make sure your app is running with an active XR session, in Meta XR Simulator or on a connected headset.
The layer doesn’t load	Keep the layer library and its `.json` manifest in the same folder, and confirm `XR_ENABLE_API_LAYERS` matches the manifest `name` (`XR_APILAYER_METAX_operator`).
Port `8720` already in use	Close other running XR apps or MCP server instances, then start your app again.
macOS blocks the proxy or layer	Allow them under System Settings > Privacy and Security.