Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Chrrxs/robloxstudio-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Every Roblox Studio MCP tool that operates on a specific Studio window accepts an instance_id parameter to route the call to the right place. get_connected_instances is how you discover those IDs — it returns a snapshot of every Studio session currently connected to the MCP server, along with metadata about each session’s role, version, playtest state, and plugin health. It is the foundational routing tool for any workflow that involves multiple open places or active playtests.

​
Parameters

get_connected_instances has no required parameters. It returns data for all connected instances regardless of input.
​
instance_id
string
Accepted but has no effect on this tool. get_connected_instances always returns the complete list of connected instances.

​
Response fields

Each entry in the returned array represents one connected Studio plugin instance and contains the following fields:
FieldTypeDescription
instanceIdstringUnique routing ID. Format: "place:PlaceId" for published places; "anon:uuid" for locally-opened or revision-based windows. Pass this value as instance_id in any other tool call.
rolestringThe DataModel peer type: "edit" for the authoring session, "server" for the play-server, "client-1", "client-2", etc. for playtest clients.
placeIdnumberThe numeric Roblox place ID, if the place has been published. null for anonymous local places.
placeNamestringHuman-readable place name as reported by the plugin.
dataModelNamestringInternal DataModel name ("edit", "run", etc.).
isRunningbooleantrue when a playtest is currently active in this Studio window. Use this to confirm server/client peers exist before calling eval_server_runtime or eval_client_runtime.
pluginVersionstringVersion string of the Studio plugin currently connected.
serverVersionstringVersion string of the MCP server process.
versionMismatchbooleantrue when pluginVersion and serverVersion differ. The plugin continues to function but shows a yellow warning banner.
pluginVariantstring"main" for the full read-write plugin; "inspector" for the read-only inspector variant.
lastActivitynumberUnix timestamp (milliseconds) of the last message received from this instance.
connectedAtnumberUnix timestamp (milliseconds) when this instance first connected.

​
When to use get_connected_instances

​
Resolving a routing error

When you call any tool without an instance_id and more than one Studio window is connected, the MCP server returns a multiple_instances_connected error. The error response embeds the instance list directly in its data field — so a separate get_connected_instances call is often unnecessary. However, if you need a fresh, current snapshot independently of a prior error, call get_connected_instances directly.

​
Setting up a playtest

Before starting a solo_playtest or multiplayer_playtest, use get_connected_instances to confirm which window to target (instance_id) and to verify no playtest is already running (isRunning: false).

​
Confirming runtime peers are available

Runtime eval tools (eval_server_runtime, eval_client_runtime) require a running playtest. Check isRunning: true on the edit instance and confirm that "server" and "client-1" roles appear in the list before sending eval requests.

​
Checking plugin health

If a tool behaves unexpectedly, inspect versionMismatch, pluginVersion, and serverVersion to determine whether the plugin needs to be updated. A versionMismatch: true means the plugin and server are out of sync — fully close and reopen Studio after updating the plugin.

​
Example response

The following shows two connected places: a published place in edit mode with an active playtest (server + one client), and an anonymous revision window with no playtest running. 
[
  {
    "instanceId": "place:12345678",
    "role": "edit",
    "placeId": 12345678,
    "placeName": "MyGame",
    "dataModelName": "edit",
    "isRunning": true,
    "pluginVersion": "2.20.0",
    "serverVersion": "2.20.0",
    "versionMismatch": false,
    "pluginVariant": "main",
    "lastActivity": 1749638537000,
    "connectedAt": 1749635702000
  },
  {
    "instanceId": "place:12345678",
    "role": "server",
    "placeId": 12345678,
    "placeName": "MyGame",
    "dataModelName": "run",
    "isRunning": true,
    "pluginVersion": "2.20.0",
    "serverVersion": "2.20.0",
    "versionMismatch": false,
    "pluginVariant": "main",
    "lastActivity": 1749638536000,
    "connectedAt": 1749637844000
  },
  {
    "instanceId": "place:12345678",
    "role": "client-1",
    "placeId": 12345678,
    "placeName": "MyGame",
    "dataModelName": "run",
    "isRunning": true,
    "pluginVersion": "2.20.0",
    "serverVersion": "2.20.0",
    "versionMismatch": false,
    "pluginVariant": "main",
    "lastActivity": 1749638535000,
    "connectedAt": 1749637846000
  },
  {
    "instanceId": "anon:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role": "edit",
    "placeId": null,
    "placeName": "MyGame (revision 3134)",
    "dataModelName": "edit",
    "isRunning": false,
    "pluginVersion": "2.20.0",
    "serverVersion": "2.20.0",
    "versionMismatch": false,
    "pluginVariant": "main",
    "lastActivity": 1749638281000,
    "connectedAt": 1749638119000
  }
]
In this state, to target the running server peer you would pass "instance_id": "place:12345678" and "target": "server" to tools like execute_luau or eval_server_runtime. To work in the revision window instead, pass "instance_id": "anon:a1b2c3d4-e5f6-7890-abcd-ef1234567890".
When a multiple_instances_connected error occurs, the error payload already contains the instance list in its data field — you can read instance IDs directly from the error without a second round-trip to get_connected_instances.

Build docs developers (and LLMs) love

Get started for freeTalk to us