omniverse-mcp 0.2.0__tar.gz

omniverse_mcp-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "omniverse-mcp",
+  "owner": {
+    "name": "Soma Osvay",
+    "url": "https://github.com/serionist"
+  },
+  "metadata": {
+    "description": "The Omniverse MCP plugin for Claude Code."
+  },
+  "plugins": [
+    {
+      "name": "omniverse-mcp",
+      "source": "./plugin",
+      "description": "Drive NVIDIA Omniverse Kit apps (Isaac Sim, USD Composer) from Claude Code: look at the stage, edit it, run physics, drive robots and record what happens."
+    }
+  ]
+}

omniverse_mcp-0.2.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# MCP output (generated at runtime)
+mcp_output/
+
+# Test results (generated during testing)
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+test_project/results/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local overrides
+test_project/.mcp.json
+test_project/.claude/
+
+# Claude Code local state: machine-specific settings and keys.
+.claude/settings.local.json
+.claude/worktrees/
+CLAUDE.local.md
+
+# Scratch files the skills write: review packs, issue and PR bodies.
+.local/

omniverse_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+What changed for people who use omniverse-mcp, newest first. A change users notice adds its line under Unreleased in
+the same PR. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## Unreleased
+
+## 0.2.0 (2026-10-29)
+
+The first release on PyPI: `uvx omniverse-mcp`, or the Claude Code plugin. The breaking changes below concern a clone
+of this repo from before it.
+
+### Security
+
+- **The bridge answers only the MCP server that holds its token.** Before this, any program on the machine, and any
+  web page open in a browser, could send `/execute` to the extension and run Python inside the Kit app. The extension
+  now writes a new random token to a file only your user can read, every request must carry it, and requests from web
+  pages are refused.
+
+### Breaking changes
+
+- **Update the MCP server and the Kit extension together.** A new server refuses an old extension, and an old server
+  gets 401 from a new one. `git pull` in your checkout updates both; then restart Kit and your MCP client.
+- **A remote Kit app needs the token by hand:** set the extension's `token` setting and the server's
+  `OMNIVERSE_MCP_TOKEN` to the same value.
+- **`inspect_prim` no longer takes `distance`.** It fits the distance itself; use `zoom_offset` to move closer or
+  further.
+- **`viewport_light("get")` reports `lighting_mode`** and the available modes, in place of `camera_light_on`.
+- **The Python package is `omniverse_mcp`.** In `.mcp.json`, `python -m isaac_sim_mcp` becomes the `omniverse-mcp`
+  command (or `uv run --no-sync --project <clone> omniverse-mcp`; the README shows both). An install from before
+  the rename still points `omniverse-mcp` at the deleted `isaac_sim_mcp`: reinstall it with
+  `pip uninstall omniverse-mcp` then `pip install .` (or `pip install -e .`), or switch to `uv sync`.
+- **The Kit extension is `ovmcp.bridge`, in `extension/ovmcp.bridge/`.** It was `isaacsim.mcp.bridge`, in a folder
+  named with its version. To move over:
+  1. In Kit's Extension Manager, turn `isaacsim.mcp.bridge` off and its autoload off.
+  2. Remove its search path if it pointed inside `extension/isaacsim.mcp.bridge-1.0.0`; the repo's `extension/` folder
+     stays the search path.
+  3. Turn on `ovmcp.bridge` with autoload.
+  4. Move a custom port or token from `exts."isaacsim.mcp.bridge"` to `exts."ovmcp.bridge"`. The
+     `scene_tree_max_depth` setting is gone; nothing read it.
+- **The server's flags are `--host` and `--port`,** in place of `--isaac-host` and `--isaac-port`, which now stop
+  the server with a message naming the new flag; any other unknown flag is an error too. `--host`, `--port` and
+  `--output-dir` default to `OMNIVERSE_MCP_HOST`, `OMNIVERSE_MCP_PORT` and `OMNIVERSE_MCP_OUTPUT_DIR`; an empty
+  variable counts as unset.
+- **The MCP resources are `omniverse://scene/tree` and `omniverse://sim/state`,** and the server calls itself
+  `omniverse`. Scene dumps and recording state files start with `# Omniverse MCP`, and their `# format` line
+  reads `omniverse-mcp-v1`.
+- **Python 3.11 or newer** for the server.
+- **A tool that fails returns an error result, not `ERROR:` text.** The MCP result has `isError` set, with the
+  bridge's message and the last lines of its traceback, or why the Kit app couldn't be reached; its text no
+  longer starts `ERROR:`. A script that looked for `ERROR:` in a tool's text reads `isError` instead, or it
+  takes every failure for a success. A failed resource read is a resource error.
+- **A tool refuses a value out of its range, or not one of its choices,** before it reaches Kit: a width, height,
+  count or `fps` below 1; a negative `max_depth`, `frame_index`, mass, density or friction; a distance, duration,
+  radius or point size not above 0; a `zoom_offset` of -1 or less; an opacity, roughness, metallic or restitution
+  outside 0 to 1; a `max_depth` above 15 in `get_scene_tree`, which used to cut it to 15 quietly. `sim_control`,
+  `viewport_light`, `manage_extensions` and `draw_debug` take only their listed actions and shapes, in lower case
+  (`"Play"` used to work), and `get_logs` only `verbose`, `info`, `warn`, `error`, `fatal` or `""` as `min_level`,
+  where an unknown level used to filter nothing.
+- **`clone_prim` refuses a target path that already holds a prim,** and `create_prim` one that holds a prim of
+  another type. Both used to overwrite it: a clone replaced the prim there and its children, and a create turned a
+  Cube into an Xform.
+
+### Fixed
+
+- **A capture shows the view it was asked for.** Every capture went through one temporary file, which Kit 110
+  writes after it reports the capture done, so a capture could return the previous one's image: each of
+  `inspect_prim`'s angles showed the angle before it, its first the view from before the call, and `capture_viewport`
+  and recording frames could be a step behind too. On Kit apps that wrote the file in time this didn't show.
+- **`set_material`'s colours show.** Its OmniPBR shader named only an id, which some Kit apps don't resolve
+  (Isaac Sim 6.2 headless among them): every material rendered as Kit's red error material, while the tool reported
+  success. The shader now names its MDL source, `OmniPBR.mdl`, and a material made before this gets it the next time
+  `set_material` uses it.
+- **`draw_debug`'s `size` defaults to 0.05, what it draws,** where its schema said 5.0; asking for 5.0 drew 0.05.
+- **`get_logs` names Kit's log levels right, and `min_level` keeps the right ones.** A warning was labelled
+  `verbose` and an error `info`, and `min_level="warn"` kept only fatal messages.
+
+### Changed
+
+- **The server runs on MCP SDK v2** (`mcp` 2.3.0), and its tools reach Kit one request at a time.
+- **A black capture is no longer relit behind your back.** The bridge used to turn the camera light on and capture
+  again; now the capture comes back as it is, with a warning that says how to light the scene (`viewport_light`).
+- **`inspect_prim` refuses what it cannot do instead of guessing:** an unknown angle name (it used to be skipped),
+  a non-numeric `width`, `height` or `zoom_offset`, and an orthographic viewport camera, where distance frames
+  nothing.
+
+### Added
+
+- **A Claude Code plugin,** with this repo as its marketplace: `/plugin marketplace add serionist/omniverse-mcp`,
+  then `/plugin install omniverse-mcp@omniverse-mcp`. It starts the server of its release with `uvx`, and brings
+  skills: `/omniverse-mcp:setup` installs the Kit extension and checks the connection; `scene`, `geometry`,
+  `simulate` and `script` hold the workflows and traps `docs/AI_GUIDE.md` used to. A skill pre-approves read-only
+  tools only.
+- **`get_sim_state` reports the Kit extension's release beside the server's,** and when they differ, the command
+  that installs the server's extension. A different release on the same bridge protocol works, so nothing else would
+  show that Kit still runs the old extension after an update.
+- **`docs/AI_GUIDE.md` is short:** the context every client needs, and links to the skills for the workflows.
+- **`omniverse-mcp extension install`** copies the Kit extension of the server's own release to your user data
+  folder, in place of an older one, and prints the folder Kit's extension search paths need; `omniverse-mcp extension
+  path` prints it again. When the server and the extension speak different bridge protocols, the server's message
+  names the command for its release, `uvx omniverse-mcp==X.Y.Z extension install` (from a checkout,
+  `uv run --project <checkout> omniverse-mcp extension install`), and says which side is older.
+- **Each tool says what it does to the Kit app,** as MCP annotations a client may use to ask before it runs one:
+  read-only (queries and captures), not destructive (edits), destructive (deletes and overwrites, prims or files), or
+  destructive and open world (`execute_script`, `manage_extensions`). `docs/TOOLS.md` lists them. They are hints,
+  never security.
+- **Every parameter is described in the tool's schema,** with its range or choices, so a client shows them without
+  the docs.
+- **`inspect_prim` frames the prim for you.** The camera stands where the prim's bounding sphere fills the captured
+  frame with a small margin; `zoom_offset` moves it closer (`-0.3`) or further (`0.5`). `isolate=True` hides everything
+  but the prim while it captures, keeps the scene's lights on, and puts every prim's visibility back exactly as it was;
+  what it cannot hide (inside an instance, or with time-sampled visibility) it names in `isolate_warnings`.
+- **`viewport_light(action="set", mode=...)` switches the lighting mode:** `"off"`, `"camera"`, `"stage"`, or a light
+  rig such as `"Default"`, the quickest fix for black captures. It returns an error when the mode did not change, for
+  example a light rig in a Kit app without the viewport's lighting menu.

omniverse_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Soma Osvay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

omniverse_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.5
+Name: omniverse-mcp
+Version: 0.2.0
+Summary: MCP server for AI control of NVIDIA Omniverse applications (Isaac Sim 5.x and up, USD Composer, and more)
+Project-URL: Homepage, https://github.com/serionist/omniverse-mcp
+Project-URL: Repository, https://github.com/serionist/omniverse-mcp
+Project-URL: Documentation, https://github.com/serionist/omniverse-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/serionist/omniverse-mcp/issues
+Author: Soma Osvay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,isaac-sim,mcp,model-context-protocol,nvidia,omniverse,robotics,simulation,usd
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: mcp==2.3.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/serionist/omniverse-mcp/main/docs/images/logo.svg" width="96" alt="">
+</p>
+
+<h1 align="center">Omniverse MCP</h1>
+
+<p align="center">
+  Drive NVIDIA Omniverse Kit apps (Isaac Sim, USD Composer) from Claude Code and any MCP client:<br>
+  look at the stage, edit it, run physics, drive robots and record what happens.
+</p>
+
+<p align="center">
+  <a href="https://github.com/serionist/omniverse-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/serionist/omniverse-mcp/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://github.com/serionist/omniverse-mcp/actions/workflows/codeql.yml"><img alt="CodeQL" src="https://github.com/serionist/omniverse-mcp/actions/workflows/codeql.yml/badge.svg?branch=main"></a>
+  <a href="https://github.com/serionist/omniverse-mcp/blob/main/LICENSE"><img alt="Licence: MIT" src="https://img.shields.io/badge/licence-MIT-blue"></a>
+  <a href="https://www.python.org/downloads/"><img alt="Python 3.11 | 3.12 | 3.13 | 3.14" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/serionist/omniverse-mcp/main/docs/images/hero-viewport.jpg" width="49%" alt="A Franka arm on a table with a red, a green and a blue block and a yellow ball, as capture_viewport returns it from Isaac Sim">
+  <img src="https://raw.githubusercontent.com/serionist/omniverse-mcp/main/docs/images/hero-segmentation.png" width="49%" alt="The same view's instance segmentation: each link of the arm, the table, each block and the ball in its own colour">
+</p>
+<p align="center">
+  <sub>One <code>capture_viewport</code> call in Isaac Sim 6.2: the frame, and every prim in its own colour, with the legend and the
+  screen boxes that tell the assistant what it sees.</sub>
+</p>
+
+An [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that gives AI assistants full control over NVIDIA Omniverse applications -- including **Isaac Sim 5.x and up**, USD Composer, and any Omniverse Kit-based app. Inspect scenes, manipulate objects, control robots, run physics simulations, capture viewports, record sessions, and manage extensions.
+
+```
+AI Assistant  <--MCP/stdio-->  MCP Server  <--HTTP/REST-->  Omniverse Extension
+(any MCP client)               (Python)                     (runs inside Kit app)
+```
+
+## What Can It Do?
+
+The tools, by area:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Scene** | `get_scene_tree`, `dump_scene`, `get_prim_properties`, `get_prim_bounds`, `set_prim_transform`, `create_prim`, `delete_prim`, `clone_prim`, `set_visibility`, `save_scene`, `new_scene` | Full scene graph control -- create, query, transform, and manage USD prims |
+| **Geometry & Mesh** | `get_mesh_stats`, `get_prim_face_count_tree`, `compare_prims` | Face/vertex/triangle counts, hierarchical face count trees, compare two prims or variants |
+| **USD Operations** | `flatten_usd`, `export_prim_as_file` | Flatten references into a single file, export prim subtrees as self-contained USD |
+| **Variants** | `create_variant_structure`, `set_variant_selection` | Create variant sets, switch variants with automatic FSD/Hydra handling |
+| **Materials** | `set_material`, `update_material_paths` | Create and bind PBR materials, bulk-fix material binding paths |
+| **Robot** | `create_robot`, `get_robot_info`, `get_joint_states`, `set_joint_targets` | Spawn robots from the asset library (Franka, G1, Spot, etc.), query joints, drive positions |
+| **Camera** | `set_camera`, `look_at_prim`, `inspect_prim`, `capture_viewport`, `viewport_light` | Position cameras, orbit-capture from multiple angles, capture viewport with instance segmentation + screen-space bounding boxes, manage viewport lighting |
+| **Simulation** | `sim_control`, `get_sim_state` | Play/pause/stop/step simulation, query state (time, FPS, up axis) |
+| **Recording** | `start_recording`, `stop_recording`, `get_recording_frame` | Capture simulation frames + prim state over time for analysis |
+| **Physics** | `set_physics_properties`, `apply_force`, `raycast` | Set mass/friction/restitution, apply forces, cast rays for spatial queries |
+| **Debug** | `draw_debug` | Draw lines, spheres, and points in the viewport for visualisation |
+| **Logging** | `get_logs` | Query Omniverse log entries (errors, warnings) for diagnosing tool failures |
+| **Scripting** | `execute_script` | Run Python inside the sim with `mcp` bridge for async MCP handler access |
+| **Extensions** | `manage_extensions` | List, enable, and disable Omniverse extensions |
+
+**Key capabilities:**
+- **Scene understanding** -- `capture_viewport` outputs a screenshot, screen-space bounding boxes, and instance segmentation (a unique colour per prim) so the AI knows what it sees
+- **Simulation recording** -- capture frames + prim state during physics, review any frame after
+- **File-based output** -- large scene dumps in grep-friendly text format, images saved as PNGs
+- **Arbitrary scripting** -- run any Python code inside the sim via `execute_script`; also serves as a fallback if any tool fails
+- **10 built-in robots** -- franka, ur10, carter, jetbot, g1, go1, go2, h1, spot, anymal
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/serionist/omniverse-mcp/main/docs/images/inspect-orbit.jpg" width="100%" alt="The workcell from four corners, as inspect_prim frames it with everything else hidden">
+</p>
+<p align="center">
+  <sub><code>inspect_prim(prim_path="/World/Workcell", angles=[the four top corners], isolate=True)</code>: one call, every side,
+  framed to fit, the rest of the stage hidden.</sub>
+</p>
+
+## Install
+
+You need a Kit app of Kit 107 or later (Isaac Sim 5.x and up, USD Composer) and [uv](https://docs.astral.sh/uv/getting-started/installation/),
+which runs the server. Two parts: the MCP server your AI client starts, and the Kit extension `ovmcp.bridge` inside
+the Kit app, both from the same release.
+
+### Claude Code: the plugin
+
+```
+/plugin marketplace add serionist/omniverse-mcp
+/plugin install omniverse-mcp@omniverse-mcp
+```
+
+Then run `/omniverse-mcp:setup`: it installs the Kit extension of the plugin's release, walks you through turning it on
+in Kit, and checks the connection. The plugin also brings skills for working on scenes, geometry, simulation and
+scripts, which Claude uses when a request fits ([the plugin](https://github.com/serionist/omniverse-mcp/blob/main/plugin/README.md)).
+
+### Other MCP clients: uvx
+
+Add the server to your client's MCP configuration, such as a project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "omniverse": { "command": "uvx", "args": ["omniverse-mcp"] }
+  }
+}
+```
+
+Install the extension of the same release and turn it on in Kit (below). `uvx` fetches the newest release the first
+time and keeps it until its cache is refreshed; `uvx omniverse-mcp@latest extension install` fetches the newest server
+and installs its extension. Copy [`docs/AI_GUIDE.md`](https://github.com/serionist/omniverse-mcp/blob/main/docs/AI_GUIDE.md) into
+your client's instruction file (`AGENTS.md`, `.cursorrules`): the context every session needs, with links to the
+skills that hold the workflows and traps; copy the ones your work needs too.
+
+### The Kit extension
+
+```bash
+uvx omniverse-mcp extension install
+```
+
+It copies `ovmcp.bridge` into your user data folder and prints that folder. Then, once, in the Kit app:
+
+1. **Window > Extensions**, the menu (☰) at the top right, **Settings**.
+2. Under **Extension Search Paths**, the green **+**, then paste the folder it printed. The **+** adds an empty row:
+   click it to type.
+3. Search for `ovmcp` under **THIRD PARTY**, and turn **Omniverse MCP Bridge** on, with **Autoload**.
+4. Quit with **File > Exit**, which is when Kit saves these settings, and start it again. The console shows
+   `[ext: ovmcp.bridge-<version>] startup`.
+
+A headless or scripted Kit takes `--ext-folder <that folder> --enable ovmcp.bridge` instead. `omniverse-mcp extension
+path` prints the folder again.
+
+> **Updating:** install the extension again after each server update, and restart Kit and your client. On Windows a
+> running Kit holds the folder: quit it first. With the plugin, `/omniverse-mcp:setup` does this.
+
+> **Used the extension before?** Before 0.2.0 it came from a clone of this repo, and before that it was
+> `isaacsim.mcp.bridge`. Turn the old one off and remove its search path, so Kit loads one copy. See the
+> [changelog](https://github.com/serionist/omniverse-mcp/blob/main/CHANGELOG.md).
+
+### From a clone
+
+For working on omniverse-mcp itself:
+
+```bash
+git clone https://github.com/serionist/omniverse-mcp.git
+cd omniverse-mcp
+uv sync
+```
+
+The client starts the server from the clone, and the Kit extension search path takes the clone's `extension/`
+folder, so a `git pull` updates both (restart Kit and the client after it):
+
+```json
+{
+  "mcpServers": {
+    "omniverse": { "command": "uv", "args": ["run", "--no-sync", "--project", "<REPO_PATH>", "omniverse-mcp"] }
+  }
+}
+```
+
+`--no-sync` starts the server from the environment `uv sync` built, so a client never waits on a download at start,
+and the server still writes its files under your project's `mcp_output/`. [CONTRIBUTING](https://github.com/serionist/omniverse-mcp/blob/main/CONTRIBUTING.md) has the rest.
+
+### Go
+
+With the Kit app running, open your AI client in the project and ask: *"What's in the scene right now?"*
+
+## Context7 for scripts
+
+Models are not trained on Omniverse and Isaac Sim APIs, and guess their names. With [Context7](https://context7.com)
+as a second MCP server, the assistant looks the API up (library `isaac-sim/isaacsim`) before writing `execute_script`
+code; the server's instructions and the `script` skill ask it to.
+
+## Examples
+
+> "Create a table with a red cube on top of it, and point a spotlight at it."
+
+> "Spawn a Franka arm at the origin, then move its joints to a pick-ready pose."
+
+> "Start recording, play the sim for 3 seconds, then show me what happened to the robot."
+
+> "Move the apple so it's sitting on top of the desk. Use bounding boxes to compute the correct position."
+
+> "Inspect the G1 robot from all angles so I can see its current pose."
+
+## Configuration
+
+### The server
+
+```
+omniverse-mcp [--host HOST] [--port PORT] [--output-dir DIR]    the MCP server, over stdio
+omniverse-mcp extension install                                 install the Kit extension of this release
+omniverse-mcp extension path                                    print the folder Kit's search paths need
+
+--host          Kit extension host (default: OMNIVERSE_MCP_HOST, else 127.0.0.1)
+--port          Kit extension port (default: OMNIVERSE_MCP_PORT, else 8211)
+--output-dir    Directory for file outputs (default: OMNIVERSE_MCP_OUTPUT_DIR, else ./mcp_output/)
+```
+
+The plugin's server takes the same variables from the environment Claude Code starts in.
+
+### The extension's settings
+
+Kit settings, in the extension's `config/extension.toml` or on Kit's command line (`--/exts/ovmcp.bridge/port=8212`):
+```toml
+[settings]
+exts."ovmcp.bridge".host = "127.0.0.1"
+exts."ovmcp.bridge".port = 8211
+exts."ovmcp.bridge".token = ""
+```
+
+### The bridge token
+
+The extension runs any Python the MCP server sends, so it answers only a server that holds its token. At every start
+it writes a new token to a file only your user can read, and the MCP server on the same machine picks it up: nothing
+to set up. Requests from web pages are refused. See [Architecture](https://github.com/serionist/omniverse-mcp/blob/main/docs/ARCHITECTURE.md#the-bridge-token) for where the
+file lives.
+
+For a remote setup, set the extension's `token` to a long random value and give the MCP server the same value in the
+`OMNIVERSE_MCP_TOKEN` environment variable. Anyone with the token can run code in your Kit app.
+
+## Troubleshooting
+
+**"Missing or wrong bridge token"** -- Is Kit running the extension on this machine, as your user? If Kit runs as another user, in a container or on another machine, use the `token` setting and `OMNIVERSE_MCP_TOKEN` (above).
+
+**"The Kit extension is older than this MCP server", or "speaks bridge protocol"** -- The server and the extension come from different releases. Run the command the message names (or `git pull` in a clone), then restart Kit so it loads the new extension.
+
+**"Kit app connection failed", refused or timed out** -- Is the Kit app running, with the extension on? Its console shows `[ext: ovmcp.bridge-<version>] startup`. The server looks for it on port 8211 unless `OMNIVERSE_MCP_PORT` or `--port` says otherwise.
+
+**The plugin's server doesn't start** -- `/mcp` in Claude Code shows its error. Is `uv` on the PATH Claude Code starts with?
+
+**Viewport capture returns black** -- The response includes a WARNING with the lighting mode. Use `viewport_light("get")` to see the mode and whether the scene has lights, then `viewport_light(action="set", mode="Default")` for a light rig, or `mode="camera"` for a light that follows the camera, and recapture. Kit 105.1+ has no default stage light, so scenes without explicitly added lights will render black.
+
+**Tools return errors** -- Check the Omniverse console for tracebacks. Some tools need the sim to have played once (`get_joint_states`, `raycast`). Robot tools require Isaac Sim specifically.
+
+## Documentation
+
+- [Tool Reference](https://github.com/serionist/omniverse-mcp/blob/main/docs/TOOLS.md) -- Every tool, with its parameters, hints and examples
+- [Architecture](https://github.com/serionist/omniverse-mcp/blob/main/docs/ARCHITECTURE.md) -- How the two-process bridge works
+- [The plugin](https://github.com/serionist/omniverse-mcp/blob/main/plugin/README.md) -- What the Claude Code plugin brings, and its skills
+- [AI Assistant Guide](https://github.com/serionist/omniverse-mcp/blob/main/docs/AI_GUIDE.md) -- For other clients' instruction files
+- [Contributing](https://github.com/serionist/omniverse-mcp/blob/main/CONTRIBUTING.md) -- How to contribute
+
+## Licence
+
+[MIT](https://github.com/serionist/omniverse-mcp/blob/main/LICENSE). Not affiliated with or endorsed by NVIDIA; Omniverse and Isaac Sim are NVIDIA's trademarks.