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
- A Cyango account and xr/studio with your story open. The live editor is where MCP edits land.
- An AI app that supports remote MCP servers, for example ChatGPT, Claude, Cursor or Grok.
- 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/mcpand 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-mcpskill.
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-propertiesbefore editing UI entities. - Verification helpers —
bridge_statuswhen connection or queue issues appear;validate_patchbefore risky patches;instantiate_prefabwhen 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_statusinstead 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.