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.

Roblox Studio MCP is built on three cooperating layers: an MCP server that speaks to AI clients over stdio, an HTTP bridge server that queues work for Studio plugins, and a Roblox plugin that runs inside every open Studio window. Each layer has a single, clear responsibility—the AI client never talks directly to Studio, and Studio never needs to understand the MCP protocol. The bridge in the middle keeps both sides decoupled, allowing multiple Studio windows to share one server without any additional configuration.

​
Layer 1 — MCP Server

The outermost layer is RobloxStudioMCPServer, defined in packages/core/src/server.ts. It wraps @modelcontextprotocol/sdk’s Server class and communicates with the AI client (Claude, Cursor, Codex, Gemini, etc.) exclusively over stdio using JSON-RPC 2.0 — the standard MCP transport. When the AI client connects it receives two handlers:
  • tools/list — returns the full tool catalog with names, descriptions, and JSON schemas.
  • tools/call — dispatches a named tool call to TOOL_HANDLERS in http-server.ts, which in turn calls the matching method on RobloxStudioTools.
// Simplified excerpt from server.ts
const server = new RobloxStudioMCPServer({
  name: 'robloxstudio-mcp',
  version: VERSION,
  tools: getAllTools(),          // 80 advertised tools (full edition)
  callableTools: getAllCallableTools(),
});
server.run();
The callableTools list is the set of tools that can actually be dispatched; tools is what the AI client sees. This separation lets deprecated tool names remain callable without appearing in tools/list.
The MCP server also exposes a Streamable HTTP MCP endpoint at http://localhost:58741/mcp for clients that prefer HTTP transport over stdio.

​
Layer 2 — HTTP Bridge

When RobloxStudioMCPServer.run() is called it starts an Express HTTP server (default port 58741, overridden by ROBLOX_STUDIO_PORT). This server is the meeting point between the MCP layer and the Studio plugin layer. How a tool call travels through the bridge:
  1. RobloxStudioTools calls BridgeService.sendRequest(endpoint, data, targetInstanceId, targetRole).
  2. BridgeService generates a UUID request ID, enqueues the request as a PendingRequest, and waits on a Promise.
  3. The Studio plugin polls /poll?pluginSessionId=<guid> every 500 ms and receives the pending request.
  4. The plugin executes the corresponding Luau API call and POSTs the result back to /response with { requestId, response }.
  5. BridgeService.resolveRequest() resolves the Promise, and the result travels back up through RobloxStudioTools → TOOL_HANDLERS → the MCP tools/call response.
AI Agent  ──stdio──►  MCP Server  ──BridgeService──►  HTTP :58741
                                                           │
                                         ◄── /poll ──  Studio Plugin
                                         ──  /response ►
Key HTTP endpoints used by the plugin:
EndpointMethodPurpose
/readyPOSTPlugin registers on startup, receives assignedRole
/pollGETPlugin fetches the next pending request
/responsePOSTPlugin posts execution results
/disconnectPOSTPlugin deregisters on unload
/healthGETReturns connection status, versions, pending request count
/statusGETLightweight status for monitoring
The /health and /status endpoints are useful for debugging. They return pluginVersion, serverVersion, versionMismatch, instanceCount, and pendingRequests for every connected Studio window.

​
Proxy Mode

When two AI client sessions are running simultaneously (for example, Claude and Cursor both connected to the same Studio), the second session’s RobloxStudioMCPServer cannot bind port 58741 — it’s already held by the first. Rather than failing, the second server automatically enters proxy mode:
  • It creates a ProxyBridgeService instead of a BridgeService.
  • Every sendRequest call is forwarded as a POST to http://localhost:58741/proxy on the primary server.
  • The primary server’s bridge queue and the single plugin polling loop handle execution.
  • The proxy mirrors the primary’s instance list via periodic GET /instances calls (every 1 second) so that resolveTarget and get_connected_instances work correctly in both sessions.
// From proxy-bridge-service.ts — forwarding a tool call to the primary
const response = await fetch(`${this.primaryBaseUrl}/proxy`, {
  method: 'POST',
  body: JSON.stringify({ endpoint, data, targetInstanceId, targetRole, proxyInstanceId }),
});
If the primary server shuts down, proxy sessions promote themselves to primary by attempting to re-bind port 58741 every 5 seconds (configurable via ROBLOX_STUDIO_PROXY_PROMOTION_INTERVAL_MS).

​
Layer 3 — Studio Plugin

The Studio plugin is a compiled Roblox plugin file (.rbxmx) that runs inside every open Studio window. It is installed to the Roblox Plugins folder either manually (--install-plugin) or automatically at server startup (--auto-install-plugin). On load, the plugin:
  1. Determines its role: edit (the editable DataModel), server (play-server DataModel), or client-N (play-client DataModel).
  2. POSTs to /ready with { pluginSessionId, instanceId, role, placeId, placeName, isRunning, pluginVersion }.
  3. Starts a polling loop — every 500 ms it calls /poll?pluginSessionId=<guid>. If a pending request is returned, the plugin executes it using Roblox Luau APIs and POSTs the result back.
Studio Plugin (edit DM)   →  POST /ready  →  BridgeService.registerInstance()
                          →  GET  /poll   →  returns PendingRequest (or null)
                          ←  [executes Luau API call in Studio]
                          →  POST /response { requestId, result }
The plugin is auto-activated for edit and server roles without user interaction. Client roles are activated by the server-side ClientBroker after playtests start.

​
Request Timeout

Every pending request has a 30-second timeout. If the Studio plugin does not poll and respond within 30 seconds, BridgeService rejects the Promise with "Request timeout". This surfaces to the AI client as a tool error. Common causes are Studio being minimized, the render loop paused, or the plugin not yet registered.

​
Version Mismatch Handling

When the plugin’s reported pluginVersion differs from the server’s serverVersion, the bridge sets versionMismatch: true on the PluginInstance. The plugin continues to operate normally but shows a yellow warning banner in the Studio UI. The mismatch is reported in:
  • The /health and /status HTTP responses.
  • The get_connected_instances MCP tool result.
  • Server stderr at the moment of /ready registration.
A version mismatch means the plugin’s tool implementations may not match what the server expects. Run npx -y @chrrxs/robloxstudio-mcp@latest --install-plugin (or --auto-install-plugin) and fully reopen Studio to resolve it.

​
Startup Sequence Summary

1

MCP server starts

npx @chrrxs/robloxstudio-mcp@latest launches. If --auto-install-plugin is passed, the matching .rbxmx file is copied to the Roblox Plugins folder before the server binds the port.
2

HTTP bridge binds

The server claims port 58741. If the port is taken, proxy mode activates and requests are forwarded to the primary on port 58741.
3

AI client connects

Claude, Cursor, Codex, or Gemini connects over stdio. The server responds to tools/list with the full tool catalog.
4

Studio plugin registers

Each open Studio window’s plugin POSTs to /ready. The bridge registers the instance and assigns it a routing key (instanceId) and role.
5

Tool calls flow

The AI client issues a tool call → MCP server → BridgeService queue → plugin poll → Luau execution → /response → resolved Promise → tool result back to AI client.

Build docs developers (and LLMs) love

Get started for freeTalk to us