English

xr/studio Documentation

AI agents & Cyango MCP

Install the cyango-mcp skill, connect MCP to xr/studio, and use AI agents safely with batched tools and official rules.

AI agents and Cyango MCP

Cyango MCP connects an AI assistant (for example Cursor, Claude Code, or another MCP-capable client) to xr/studio while you edit. The assistant can read scene state and apply structured changes through tools instead of clicking every control by hand.

This page explains how to connect your AI app to the hosted Cyango MCP server, then add the official cyango-mcp skill so automations follow Cyango’s rules. Protocol details live in the skill; here we focus on setup and habits.

What you need first

  1. A Cyango account and xr/studio with your story open. The live editor is where MCP edits land.
  2. An AI app that supports remote MCP servers, for example ChatGPT, Claude, Cursor or Grok.
  3. Patience with batches. Agents should send few, grouped operations (many tiny sequential writes can stress the bridge). The bundled skill explains batching in depth.

Connect your AI app

The Cyango MCP server is hosted at this URL:

https://mcp.cyango.com/mcp

The first time your AI app connects, it opens a Cyango sign-in page. Sign in with your Cyango account, then select Allow. You do not install or run anything on your computer.

ChatGPT

Install the Cyango plugin from the ChatGPT plugin directory. You can also add the server yourself: open the Plugins page in ChatGPT, select Add custom MCP server, and enter the URL above. Your plan and workspace settings decide whether custom servers are available.

Claude

  • Claude Code: run claude mcp add --transport http cyango https://mcp.cyango.com/mcp, then run /mcp and sign in.
  • Claude (web and desktop app): add a custom connector with the URL above.
  • Claude plugin: install the Cyango plugin. It adds the server and the cyango-mcp skill.

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project):

{
  "mcpServers": {
    "cyango": {
      "url": "https://mcp.cyango.com/mcp"
    }
  }
}

Then open Settings → MCP and sign in to the cyango server.

Grok

Run grok mcp add --transport http cyango https://mcp.cyango.com/mcp. Grok opens the sign-in page in your browser.

Other apps

Any app that supports remote MCP servers over HTTP with OAuth sign-in can use the same URL.

Connect xr/studio

Open xr/studio with the same Cyango account, open Story Settings → MCP Bridge, and select Connect MCP. Then ask your agent to use Cyango tools (list scenes, patch entities, etc.).

Only one tab receives the edits. When you connect MCP in a second tab, that tab takes over, and the first tab shows Use this tab.

Connect xr/stores

To let the agent manage your product catalog, open xr/stores, select the link icon in the header, and select Connect MCP. The icon turns green when the agent is connected. From xr/stores the agent can work on products only. To edit a story, connect MCP in xr/studio again.

Install the cyango-mcp skill

Cyango publishes agent skills in @cyango-tools/skills. Install the MCP skill into your project so your assistant loads rules automatically:

npx @cyango-tools/skills@latest install cyango-mcp

That copies the skill into .agents/skills/cyango-mcp/. Cursor and similar tools typically discover skills under .agents/skills/ without extra wiring.

Prefer pinned installs: use @latest (or pin a version) so npx does not reuse an old cached CLI tarball.

Manual install

If you skip the CLI, copy skills/cyango-mcp/ from the skill package into .agents/skills/cyango-mcp/ in your repo — same layout as the installer.

Updating

Skills ship only from npm, not from Git clones. Re-run the install command when you want newer rules:

npx @cyango-tools/skills@latest install cyango-mcp

What the skill teaches the agent

The cyango-mcp skill is the canonical guide for:

  • Batched writes — create, remove, and patch entities and scenes using plural tools (add_entities, update_entities, remove_entities, and the matching scene tools). Agents should avoid long chains of one-off legacy commands.
  • Hierarchy and transforms — world vs local space, parenting order, and GUI vs 3D structure (GUI_SCREEN, GUI_CONTAINER, GROUP, …).
  • GUI layout — desktop-first breakpoints, schema-safe values, and reading gui-properties before editing UI entities.
  • Verification helpers — bridge_status when connection or queue issues appear; validate_patch before risky patches; instantiate_prefab when dropping prefabs from your library.
  • XR Stores: link the story to a connected shop (set_story_ecommerce_store), browse its products (list_store_products), and place products or make your own entities open a product page (add_product_entities, assign_products). In Cyango shops the agent can also create, edit, delete and move products (create_products, update_products, delete_products, move_products). Products that a story uses are not deleted or moved. Shopify products keep their names, prices and stock from Shopify. Shops and orders stay in the xr/stores dashboard.

Skill docs cross-reference entity families (lights, panorama, models, actions, timeline). Point your agent at “follow .agents/skills/cyango-mcp/SKILL.md” for any XR editing task.

How to prompt effectively

  • Name the goal — scene type, target entities, or UX outcome (“add a desktop HUD with two buttons that navigate scenes”).
  • Mention the skill — “Use the cyango-mcp skill rules for GUI defaults and hierarchy.”
  • Escalate debugging — if the viewport looks wrong but the tool reported success, ask the agent to inspect state with read/list tools or bridge_status instead of blindly repeating writes.

Relationship to other docs

The xr/studio manual walks through how to build stories in the editor from the user's point of view; MCP tools mirror those same scene, entity, and actions structure in machine-readable form.