> 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 your agent 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="<https://youtu.be/xp0ra7jLBIA?si=8axPWhskgnxwEBzz>" %}

## What Sandbox Studio MCP can do

Once your agent is connected, it 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 your AI coding assistant, 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). An external agent does not use those tabs. Setup for those tabs is on [Installing Sandbox Studio](https://studio-docs.sandbox.game/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 your agent 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 your agent

Open your AI coding assistant and select the folder used by the Sandbox Studio project. In Cursor, use File → Open Folder. Keeping both applications focused on the same project helps the MCP act on the intended scene.
{% endstep %}

{% step %}

## Open your agent's MCP settings

Open the MCP settings in your agent and find Sandbox Studio MCP.

In Cursor, open Settings, then Customise, then select MCP.
{% endstep %}

{% step %}

## Connect Sandbox Studio MCP

Enable or connect Sandbox Studio MCP and wait until your agent shows it is connected. In Cursor, a green status confirms that Cursor can communicate with the open Sandbox Studio editor.

{% hint style="info" %}
If Sandbox Studio MCP does not connect, follow [Troubleshooting](#troubleshooting). Confirm the project is open, Enable Sandbox Studio MCP is on, your agent has the same folder open, reload the MCP in your agent, and the port matches AI Settings → MCP. In Cursor, Reload is under Settings → Customise → MCP.
{% endhint %}
{% endstep %}

{% step %}

## Send a small test prompt

Ask your agent 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 your agent 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 **your agent**. The MCP only works while Studio is running, a project is open, and your agent 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, your agent must use that number.
5. If your agent reports **unauthorized**, connection details are stale. Use **Configure** on the MCP tab (or copy the connection details again) and reconnect in your agent.

### In your agent

Connect Sandbox Studio MCP in your agent's MCP settings, reload it if the status is not connected, and confirm the same project folder is open.

### 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 connected                                   | Studio running, project open, Enable Sandbox Studio MCP on, then reload the MCP in your agent. In Cursor, Reload is under Customise → MCP, and a green status means connected. 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 your agent.                                                                                                         |
| 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 your agent 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 your agent.                                                                                                 |

{% hint style="info" %}
*NOTE: A connected status (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 your agent 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://studio-docs.sandbox.game/working-efficiently-with-ai/set-up-and-use-sandbox-studio-mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
