> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md). # Set up and use Sandbox Studio MCP Connect Cursor to an open Sandbox Studio project through Sandbox Studio MCP, verify the local connection, and use prompts to create and refine scene content. {% embed url="" %} ## What Sandbox Studio MCP can do Once Cursor is connected, the agent can work in the open Sandbox Studio editor the same way you would: it reads the scene, then changes what is in it. It can: * **Read the scene and project** — the node list, a node's properties and materials, what is selected, the active scene, Play mode state, assets, and build errors * **Change the scene** — add, delete, or move nodes; set properties; change materials and colours; place prefabs and primitives. The same edits work when you are inside a prefab * **Manage scenes** — open, save, create, duplicate, or switch the active scene * **Drive the editor** — enter or exit Play mode, frame the selection, undo and redo (including while editing a prefab), take screenshots * **Work with assets** — create folders and materials, import assets, rename or move files, merge meshes, install an asset pack * **Navmesh** — generate, clear, import or export a navmesh, and toggle debug view * **Build** — rebuild the project so new code classes show up in the editor, and bake lightmaps * **Diagnose** — read build errors and the editor console ## Scene edits vs code edits Use Sandbox Studio MCP for anything you can see and click in the editor: placement, transforms, materials, colours, lights, cameras, per-instance properties, prefab overrides, scene files, navmesh, and Play mode. Use TypeScript (in Cursor, on project files) for reusable gameplay: new node classes, input, UI logic, networking, and systems. New behaviour is written in code first, then placed and configured in the scene through Sandbox Studio MCP. Do not use one-off code to change how an editor-placed object looks — that is a scene edit. {% stepper %} {% step %} ## Open the Sandbox Studio project Open the project you want Sandbox Studio MCP to work with and leave it open in Sandbox Studio while you configure the connection. {% endstep %} {% step %} ## Open AI Settings In Sandbox Studio, open the menu, then App Settings, then AI Settings. Select the **MCP** tab. The **Assistant** and **Models** tabs on this same window are for the **in-editor** chat (providers, pinned models, Default Agent Model). They are not required for Cursor. Setup for those tabs is on [Installing Sandbox Studio](/getting-started/installing-sandbox-studio.md#set-up-in-editor-ai-assistants-without-cursor). {% endstep %} {% step %} ## Enable Sandbox Studio MCP Turn on Enable Sandbox Studio MCP if it is off. Status should show that it is running. If it is already on, leave it on so Cursor can connect. {% endstep %} {% step %} ## Review the connection settings On the MCP tab, note the local port in the status line. The current editor shows **Running on port 17350** and the URL `http://127.0.0.1:17350/mcp`. If your port number is different, use the number shown on your screen. Review Auto-Approve By Default and the permission list before allowing the MCP to change the project. {% hint style="info" %} Sandbox Studio MCP connects locally to Sandbox Studio. Automatic approvals can let requested actions run with less confirmation, so enable only the permissions that suit your workflow. {% endhint %} {% endstep %} {% step %} ## Open the same project folder in Cursor Open Cursor and select the folder used by the Sandbox Studio project. Keeping both applications focused on the same project helps the MCP act on the intended scene. {% endstep %} {% step %} ## Open Cursor's MCP settings In Cursor, open Settings, then Customise, then select MCP. Find Sandbox Studio MCP in the available MCP connections. {% endstep %} {% step %} ## Connect Sandbox Studio MCP Enable or connect Sandbox Studio MCP and wait for its status to turn green. A green status confirms that Cursor can communicate with the open Sandbox Studio editor. {% hint style="info" %} If Sandbox Studio MCP does not turn green, follow [Troubleshooting](#troubleshooting). Confirm the project is open, Enable Sandbox Studio MCP is on, Cursor has the same folder open, Reload the MCP in Settings → Customise → MCP, and the port matches AI Settings → MCP. {% endhint %} {% endstep %} {% step %} ## Send a small test prompt Ask Cursor to make one clear, visible change so you can confirm that the connection works. For example: > Create a simple house from primitives and place it in the scene. > {% endstep %} {% step %} ## Confirm the editor change Watch Cursor for the Sandbox Studio MCP tool activity, then switch to Sandbox Studio and check that the requested primitives appear in the scene. {% endstep %} {% step %} ## Refine the scene with a follow-up prompt Describe the next change in relation to what is already present. Include placement, spacing, colour, lighting, scale, or material details that matter to the result. > Create a second house beside the first, leave a clear gap between them, and change the lighting to a warm sunset. > {% endstep %} {% step %} ## Review and correct the result Inspect the updated scene and give a more specific follow-up when an object, material, or light does not look right. Sandbox Studio MCP can use the editor tools exposed to it to move and scale objects, create geometry, adjust materials, change lighting, and modify supported settings. {% hint style="info" %} Change one or two related things per prompt. Small, verifiable requests make it easier to identify which instruction produced the result and to correct it when needed. {% endhint %} {% endstep %} {% step %} ## Use screenshots for visual iteration When screenshot tools are available to the MCP, ask it to capture the editor, compare the current scene with your description or reference, and continue making targeted adjustments. Review each iteration and approve actions according to your settings. {% endstep %} {% endstepper %} ## Troubleshooting Work through **Sandbox Studio** first, then **Cursor**. The MCP only works while Studio is running, a project is open, and Cursor is talking to the same local port. ### In Sandbox Studio 1. Confirm the project is open (not only the home screen). 2. Open the menu → **App Settings** → **AI Settings** → **MCP**. 3. Turn **Enable Sandbox Studio MCP** on. Status should show it is running. 4. Read the port on that tab (for example **Running on port 17350** and `http://127.0.0.1:17350/mcp`). If the number is different, Cursor must use that number. 5. If Cursor reports **unauthorized**, connection details are stale. Use **Configure** on the MCP tab (or copy the connection details again) and reconnect in Cursor. ### In Cursor 1. Open **Settings** → **Customise** → **MCP**. 2. Find **Sandbox Studio MCP**. If it is off, enable it. 3. If status is not green, use **Reload** on that MCP entry. 4. If more than one MCP row points at the same Sandbox Studio server, open each one and check the user/account and URL. Duplicate connections to the same port confuse the client — keep one working row and disable or remove the extras. 5. Confirm Cursor has the **same project folder** open as Sandbox Studio. ### Symptoms | What you see | What to do | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | MCP is not green in Cursor | Studio running, project open, Enable Sandbox Studio MCP on, then Reload in Cursor Customise → MCP. Match the port on Studio's MCP tab. | | Unauthorized / auth error | Re-run Configure (or recopy connection details) in Studio AI Settings → MCP, then reconnect in Cursor. | | No project / `project_none` / agent cannot see a scene | Open a project in Sandbox Studio and leave it in the editor. Home-only is not enough. | | Wrong scene or no tools | Same folder in Cursor and Studio. One MCP connection, not two copies of Sandbox Studio MCP. | | Port conflict or connection refused | Only one Studio instance using that port. Use the port printed in AI Settings → MCP, not an old number from a previous session. | | Tools run but the scene does not change | Approvals: check Auto-Approve and the permission list on Studio's MCP tab, and any pending approval in Cursor. | {% hint style="info" %} *NOTE: Green in Cursor means the local connection is up. It does not mean every action is auto-approved.* {% endhint %} ## What you’ve done Sandbox Studio MCP is now connected to Cursor and can carry out supported Sandbox Studio editor actions through clear, reviewable prompts. Start with small changes, check the scene after each request, and refine the result with specific follow-ups. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://studio-docs.sandbox.game/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.