---
read_when: "Combine files on disk with Studio MCP edits and playtests"
last_reviewed: 2026-06-17
---

# Script Sync integration

Official guides:
- https://create.roblox.com/docs/en-us/scripting/sync
- https://create.roblox.com/docs/en-us/ai/build

## What Script Sync does

Script Sync lets you edit Luau scripts on your local disk with any text editor or AI agent, then syncs those files into Roblox Studio automatically. It covers disk-to-Studio mapping for services such as:

- `ServerScriptService/`
- `ReplicatedStorage/`
- `StarterPlayerScripts/`
- Other eligible service folders

Files you create or edit in those mapped folders appear as scripts in the Explorer almost immediately.

## Enable Script Sync

Script Sync is a beta feature.

1. In Studio: **File → Beta Features**.
2. Find **Script Sync**, enable it, and save.
3. Restart Studio when prompted.

## Connect each service to a disk folder

1. In the Explorer, right-click a service (for example, **ServerScriptService**).
2. Choose **Script Sync → Sync with Directory**. (Older Studio builds labeled this **Sync to**.)
3. Browse to your project folder.

Important:
- Select the top-level project folder, not the individual service folders inside it.
- If your folders are named exactly `ServerScriptService`, `ReplicatedStorage`, and `StarterPlayerScripts`, Script Sync matches them automatically.

## File naming conventions

Script Sync uses the file extension to decide which Roblox script class to create. Use the exact suffixes below:

| File | Created instance | RunContext |
| --- | --- | --- |
| `Name.server.luau` | `Script` | `Server` |
| `Name.client.luau` | `Script` | `Client` |
| `Name.local.luau` | `LocalScript` | - |
| `Name.legacy.luau` | `Script` | `Legacy` |
| `Name.plugin.luau` | `Script` | `Plugin` |
| `Name.luau` | `ModuleScript` | - |
| `init.server.luau`, `init.client.luau`, `init.local.luau`, `init.legacy.luau`, `init.plugin.luau`, `init.luau` | Same as above, using the parent folder's name | Same as above |
| Directory with no `.luau` file | `Folder` | - |

Common mistakes:
- `Test.shared.luau` does **not** create a `ModuleScript` named `Test`. It creates an instance literally named `Test.shared`. Use `Test.luau` for a `ModuleScript`.
- `Test.client.luau` creates a `Script` with `RunContext = Client`, **not** a `LocalScript`. Use `Test.local.luau` for a `LocalScript`.

## Typical project layout

The official starter project (`WaveSurvival.zip`) uses this structure:

```
WaveSurvival/
├── .gitignore
├── WaveSurvival.rbxlx          # excluded from Git by .gitignore
├── ServerScriptService/        # server logic
├── ReplicatedStorage/          # shared modules
└── StarterPlayerScripts/       # client scripts
```

Use `.gitkeep` files to preserve empty folders in Git until you add real scripts.

## Where MCP fits in

Script Sync handles scripts that map to disk. MCP handles everything else:

| Task | Use |
| --- | --- |
| Edit a `.luau` file in `ServerScriptService/` | Script Sync |
| Create a script inside `StarterGui` | MCP `multi_edit` |
| Inspect a `Part`'s properties | MCP `inspect_instance` |
| Insert a Creator Store model | MCP `insert_from_creator_store` |
| Run a quick test snippet | MCP `execute_luau` |
| Start play mode and check output | MCP `start_stop_play` + `console_output` |
| Capture a screenshot | MCP `screen_capture` |

## End-to-end verification prompt

After both Script Sync and MCP are connected, ask your agent:

> Use the Roblox MCP connection to verify Script Sync is working properly. Create `ServerScriptService/Test.server.luau`, `ReplicatedStorage/Test.luau`, and `StarterPlayerScripts/Test.local.luau` that each print a distinct message, then run `game:GetService("InstanceFileSyncService"):GetStatus(instance)` on each to confirm sync status. Start play mode, capture the output, and then delete the test scripts.

This confirms:
- MCP can create and edit scripts.
- Script Sync maps the expected folders.
- `execute_luau` and `console_output` work.
- Play mode starts and stops cleanly.

## Script Sync warnings and limitations

- **Attributes and tags are ignored.** Script Sync does not preserve `Instance:SetAttribute()` values or `CollectionService` tags. Back up your place before syncing, or store that data outside synced scripts.
- **Back up your place first.** Syncing can overwrite or delete instances if file names change or files are removed.
- **Both Script Sync and the Studio MCP server are beta features.** Behavior and menu names may change.
- **Editing a synced script through MCP can cause conflicts.** If Script Sync is active for a service, prefer editing the source file on disk. MCP edits may be overwritten on the next sync.
- **Use caution with Team Create.** Multiple authors, or an agent plus Script Sync, can overwrite each other's changes.
- **Use the Luau LSP** (for example, the `JohnnyMorganz.luau-lsp` VS Code extension) for diagnostics, autocomplete, and type-checking in the synced files.

## Best practices

- Keep place files (`.rbxl`, `.rbxlx`) out of Git; commit only source scripts and config.
- Use Script Sync for long-lived code; use MCP for ad-hoc Studio operations.
- When an agent edits a script via MCP, verify the change in the Explorer or with `script_read`.
- Run playtests frequently when iterating with an agent.

---
read_when: "Investigate MCP connection failures or review Studio access"
last_reviewed: 2026-06-17
---

# Security and troubleshooting

## Security checklist

MCP clients have broad access to your open Studio session. Follow these rules:

- [ ] Only connect MCP clients you trust.
- [ ] Use test places or copies of live places for agent experimentation.
- [ ] Keep your project under version control so you can review and revert agent changes.
- [ ] Do not commit place files (`.rbxl`, `.rbxlx`) or credentials to Git.
- [ ] Avoid running untrusted `execute_luau` snippets. Executed code can publish places, write to DataStores, make HTTP requests, access plugin-level APIs, read credentials loaded in Studio, and exfiltrate data. Run only in test places and review every snippet.
- [ ] Review generated mesh/material/procedural model insertions before publishing.
- [ ] When working in a team, coordinate so only one agent session targets a given Studio instance at a time.

## Trust model

The MCP server runs locally and communicates over `stdio`. Studio initiates the server; your AI client connects to it. While no credentials flow through the AI client directly, executed Luau runs with your signed-in Studio privileges and can access credentials stored in Studio, make network requests, and call Roblox web APIs.

## Disconnecting or disabling the server when not in use

- In Studio: **Assistant → ⋯ → Manage MCP Servers** and turn off **Enable Studio as MCP server**.
- Disconnect or remove the `Roblox_Studio` entry from your MCP client's configuration.
- Close Studio windows you are not using.

This reduces the chance of accidental or unintended agent actions.

## Common issues and fixes

### MCP tools do not appear in the AI client

1. Restart the AI client completely (not just the chat panel).
2. Restart Roblox Studio.
3. Confirm **Enable Studio as MCP server** is turned on.
4. Check the config file path or quick-connect setting.
5. If using JSON config, validate JSON syntax (missing commas are the most common cause).

### Quick connect does not list my client

- Install or update the client, then restart Studio.
- Some clients require a full machine restart of the client process to register.

### `execute_luau` returns an error

- The code runs inside Studio, so it must be valid Luau in the current context.
- Use `get_studio_state` to inspect available contexts and pass `datamodel_type` explicitly: `Edit`, `Client`, or `Server`.
- Check that instances referenced in the code exist.

### Script Sync changes are not showing up

- Verify the service is synced to the correct top-level folder.
- Ensure file names end in `.luau`.
- Check that the beta feature is enabled and Studio was restarted.
- Use `game:GetService("InstanceFileSyncService"):GetStatus(instance)` on the script to inspect sync state.

### Play mode capture or input simulation fails

- Start play mode first with `start_stop_play`.
- Wait a moment for the play session to initialize before capturing or sending input.
- Some tools require the viewport to be in a valid state.

### Multiple Studio instances are confusing the agent

- Use `list_roblox_studios` to see all open instances.
- Pass the intended `studio_id` on every call; there is no shared active-instance selection to lock.
- Close unused Studio windows when possible.

## JSON syntax quick check

A valid `mcpServers` block has entries separated by commas:

```json
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": ["/c", "%LOCALAPPDATA%\\Roblox\\mcp.bat"]
    },
    "Another_Server": {
      "command": "..."
    }
  }
}
```

Use an online JSON validator or your editor's JSON diagnostics if the config does not load.

## Getting more help

- Official MCP connection guide: https://create.roblox.com/docs/en-us/studio/mcp
- Coding harness tutorial: https://create.roblox.com/docs/en-us/ai/build
- Script Sync docs: https://create.roblox.com/docs/en-us/scripting/sync
- MCP protocol overview: https://modelcontextprotocol.io/docs/getting-started/intro

---
read_when: "Enable Studio MCP and connect a client on Windows or macOS"
last_reviewed: 2026-06-17
---

# Setup and connection

Official guide: https://create.roblox.com/docs/en-us/studio/mcp

## Quick connect

The fastest path. Studio detects supported clients installed on your machine.

Supported clients (as of the latest docs):
- Antigravity
- Codex CLI
- Claude Code
- Claude Desktop
- Cursor
- Gemini CLI
- Visual Studio Code

Steps:
1. In Studio: **Assistant → ⋯ → Manage MCP Servers**.
2. Make sure **Enable Studio as MCP server** is on.
3. Expand **Quick connect**.
4. Turn on the client you want to use.
5. Restart the AI client if its tool list does not update immediately.

If your client does not appear, install it and restart Studio.

## JSON configuration

Most MCP clients read a JSON config file. Add the `Roblox_Studio` entry under `mcpServers`.

### Windows

```json
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "%LOCALAPPDATA%\\Roblox\\mcp.bat"
      ]
    }
  }
}
```

### macOS

```json
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}
```

Notes:
- If you already have other servers, add a comma after the previous entry and paste the `Roblox_Studio` block.
- Validate JSON syntax. A missing comma or bracket prevents the config from loading.
- Paths assume the default install location. Adjust if you installed Studio elsewhere.

## CLI command

Some clients accept a raw command instead of JSON.

### Windows

```bash
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat
```

### macOS

```bash
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP
```

## Client-specific hints

**Cursor**
- Open Cursor Settings → MCP, or use the project's `.cursor/mcp.json` file.
- Paste the JSON config or use quick connect if Cursor is detected by Studio.

**Visual Studio Code + Claude Code**
- Use VS Code's settings or the workspace's `.vscode/mcp.json` for the server config.
- Install the Claude Code extension, sign in, and open the chat panel.

**Claude Desktop**
- Edit `claude_desktop_config.json` (location varies by OS) and add the `Roblox_Studio` entry.

**Codex CLI / Gemini CLI / Antigravity**
- Follow the tool's own MCP config convention; the `command`/`args` values above are what matter.

## Verify the connection

1. In Studio, open **Assistant → ⋯ → Manage MCP Servers**.
2. Look for the green indicator under **Enable Studio as MCP server** showing connected clients.
3. In your AI client, run:
   > Use the Roblox MCP to list what's in `game.Workspace`.

You may need to approve the first request or add the tool to an allowlist, depending on the client.

If no tools appear:
- Restart both Studio and the AI client.
- Check that the command path exists on disk.
- Validate your JSON config.

---
read_when: "Choose a Studio MCP tool and identify the target Studio instance"
last_reviewed: 2026-09-19
---

# MCP tool reference

Official source: https://create.roblox.com/docs/en-us/studio/mcp

Discover the target with `list_roblox_studios`, then include its `studio_id` on subsequent tool calls. Inspect the connected server's tool schemas for exact arguments; do not infer a shared active instance or reuse obsolete tool names.

## Scripts and inspection

| Tool | Use |
| --- | --- |
| `script_read` | Read a script or line range using its data-model path. |
| `multi_edit` | Apply several edits, or create a script at a new path. Requires `datamodel_type` set to `Edit`. |
| `script_search` | Fuzzy script-name search, up to 10 results. |
| `script_grep` | Search script contents, up to 50 matches. |
| `search_game_tree` | Explore instances with path, type, keyword, and depth filters. |
| `inspect_instance` | Inspect readable properties, attributes, and children. |
| `subagent` | Delegate exploration or playtesting with the `explore` or `playtest` type. |

For example: discover the intended Studio window, read `game.ServerScriptService.GameLogic` with its `studio_id`, and inspect the relevant instances before changing the script.

## Execution and playtesting

| Tool | Use |
| --- | --- |
| `get_studio_state` | Check play state and available data-model types. |
| `execute_luau` | Execute Luau in the specified `datamodel_type`: `Edit`, `Client`, or `Server`. |
| `start_stop_play` | Start or stop a playtest. |
| `get_console_output` | Retrieve the Studio output log. |
| `screen_capture` | Capture the viewport, optionally using a camera position and look-at target. |
| `character_navigation` | Move the test character to a position or instance path. |
| `user_keyboard_input` | Send ordered key, text, and wait actions. |
| `user_mouse_input` | Send ordered pointer, button, scroll, and wait actions. |

Check state before choosing an execution context. For a server-side test, start play mode, confirm that `Server` is available, execute there, and inspect `get_console_output`. Keep the same explicit `studio_id` throughout the sequence.

`execute_luau` runs code in your signed-in Studio session. Review code and use a dedicated test place before operations that can publish, access credentials, make HTTP requests, or write persistent data. A playtest is not an isolated replacement for a test experience when backend services are enabled.

## Assets and generated content

| Tool | Use |
| --- | --- |
| `generate_mesh` | Generate a textured mesh from a prompt. |
| `generate_material` | Generate a material variant and retrieve its base material and name. |
| `generate_procedural_model` | Generate a configurable model from primitive parts, optionally with image references. |
| `wait_job_finished` | Wait for a procedural generation job and inspect its final status. |
| `search_asset` | Search Creator Store or user/group/universe inventory using supported filters. |
| `insert_asset` | Insert an asset by numeric Roblox asset ID. |
| `upload_image` | Upload images from HTTP URLs and obtain asset IDs. |
| `store_image` | Load a local image and obtain a URI for another tool. |

Search before insertion, inspect asset permissions, and check generation status before using the result. Uploads create assets; a local image URI from `store_image` is not itself a published asset ID.

## Documentation and instance discovery

| Tool | Use |
| --- | --- |
| `http_get` | Retrieve allowed Roblox documentation URLs, optionally searching their content. |
| `skill` | Retrieve the Studio server's task-specific reference guidance. |
| `list_roblox_studios` | Discover window names, Studio instance IDs, and place IDs. |

Local places without place IDs are listed by name. If names collide, distinguish published places by place ID and resolve any remaining ambiguity before editing. Re-list after windows close or the intended target changes.

## Migration from older tool names

Use `subagent` with the appropriate type instead of `explore_subagent` or `playtest_subagent`; `search_asset`/`insert_asset` replace the old insertion workflow. Use `get_console_output`, `user_keyboard_input`, and `user_mouse_input` in current calls. The current documentation uses explicit `studio_id` targeting rather than `set_active_studio`.