Provides a local-first MCP bridge for authorized Roblox development, enabling live script execution, structured eval results, file watching, diagnostics, source snapshots, permission-gated script capsules, crash detection, autoexec synchronization, and a realtime dashboard for managing Roblox development clients.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Roblox Bridge Agent Run the 'test' capsule and report diagnostics"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RBA connects an MCP-capable coding agent to local Luau development clients through a bounded websocket protocol. It combines live execution, structured results, file watching, diagnostics, source snapshots, permission-gated script capsules, crash detection, autoexec synchronization, and a realtime browser dashboard.
Use RBA only in experiences and local environments you own or are explicitly authorized to test. Keep its websocket and dashboard bound to loopback unless you deliberately build a secure remote deployment around them.
Editing a script and running it are only two pieces of a dependable workflow. RBA adds the missing operational layer:
one shared local bridge that multiple MCP sessions can discover instead of fighting over ports;
structured eval responses, correlated errors, bounded queues, heartbeats, and backpressure protection;
live file and profile workflows with source validation before dispatch;
Script Capsules with explicit permissions, automatic snapshots, and reversible rollback;
a polished local command center with live clients, events, profiles, watchers, screenshots, and capsule controls;
Roblox process and heartbeat diagnostics, plus a narrowly scoped restart tool;
guarded Git helpers that stage only named files and never silently sweep the workspace;
unified autoloader synchronization for configured executor autoexec locations.
Related MCP server: dex-mcp
RBA behaves like a small operations system around scripts:
MCP client
│
▼
RBA server ─── dashboard / logs / snapshots / Git status
│
├── script capsule policy + preflight + rollback
│
▼
local websocket bridge
│
▼
RBA Luau autoloader ─── authorized Roblox development clientCapsules are an honest policy boundary, not a fake security claim. RBA can block dispatch based on static capabilities, manage source history, and control lifecycle state. It cannot provide OS-grade isolation after arbitrary Lua reaches an executor.
Requirements:
Windows, macOS, or Linux for the Node server (Windows-only helpers are clearly scoped);
Node.js 20 or newer;
an MCP-capable client;
a compatible local websocket-capable Luau environment for the client loader.
Install and verify:
git clone https://github.com/evonar543/roblox_bridge_agent.git
Set-Location roblox_bridge_agent
npm install
npm testAdd the built server to your MCP configuration, replacing the example paths:
{
"mcpServers": {
"roblox_bridge_agent": {
"command": "node",
"args": ["C:\\path\\to\\roblox_bridge_agent\\dist\\index.js"],
"env": {
"RBA_ROOT": "C:\\path\\to\\roblox_bridge_agent",
"RBA_WS_HOST": "127.0.0.1",
"RBA_WS_PORT": "33882",
"RBA_WS_PORT_RANGE": "33882-33920",
"RBA_AUTO_START_WS": "true"
}
}
}
}Then run the checked-in loader in your authorized development client:
loadstring(game:HttpGet("https://raw.githubusercontent.com/evonar543/roblox_bridge_agent/main/lua/rba_autoloader.lua"))()For a pinned or offline workflow, use lua/rba_autoloader.lua directly instead of loading the moving main branch.
The protocol-v4 loader:
uses a single-instance lifecycle and stops an older RBA generation on reload;
discovers the active websocket endpoint from a bounded local port range;
reconnects with exponential backoff and avoids connection-attempt bursts;
enforces incoming payload, queued evaluation, queued byte, duplicate request, and execution-time limits;
emits client heartbeats and structured traffic counters;
exposes _G.RBA.send, _G.RBA.log, _G.RBA.trace, _G.RBA.snapshot, _G.RBA.health, _G.RBA.showStatus, and _G.RBA.stop;
displays a compact connection panel that fades after successful status updates and reappears on errors;
can start the separately installed local Instance Manager connector from a loopback-only URL.
To keep RBA separate from Instance Manager, set either value before the loader starts:
getgenv().RBA_MODE = "rba-only"
-- or
getgenv().RBA_ENABLE_INSTANCE_MANAGER = falseA capsule manages one workspace Lua file with a stable id, display name, explicit permissions, timestamps, and source history.
Available permissions:
Permission | Static capability covered |
|
|
| executor file APIs such as |
|
|
| dynamic source/environment APIs such as |
| direct |
| unbounded or frame/update loops |
Typical flow:
rba_create_script_capsule
rba_script_preflight
rba_set_script_capsule_permissions
rba_capsule_snapshot
rba_run_script_capsule
rba_rollback_script_capsule if the experiment needs to be reversed
Snapshots live under .rba-capsules/ and are ignored by Git. Rollback captures the current source first, making the rollback itself reversible.
Start the loopback dashboard with rba_dashboard_start. The default address is http://127.0.0.1:33883/.
The RBA Script OS dashboard provides:
animated bridge health and live activity state;
connected client and selected-target visibility;
direct send/eval controls;
profiles and file watchers;
capsule creation, snapshot, and run actions;
recent events, screenshots, and context snapshots;
responsive layout and non-blocking success/error notifications.
RBA exposes tools in focused families instead of one oversized command:
Bridge: rba_ws_start, rba_ws_stop, rba_ws_status, rba_connection_info, rba_clients, rba_events
Execution: rba_send_lua, rba_eval_lua, rba_execute_file, rba_execute_bundle, rba_lua_syntax_check, rba_script_preflight
Capsules: rba_create_script_capsule, rba_list_script_capsules, rba_set_script_capsule_permissions, rba_capsule_snapshot, rba_list_capsule_snapshots, rba_rollback_script_capsule, rba_run_script_capsule
Live development: rba_watch_file, rba_start_live_session, rba_list_script_profiles, rba_set_autorun
Observability: rba_ping_clients, rba_probe_runtime, rba_context_snapshot, console mirroring, screenshots, and structured event logs
Recovery: rba_health_check, rba_detect_roblox_crash, rba_restart_roblox, rba_development_snapshot
Source safety: workspace backups, restore, batch file operations, bounded reads, and search
Workflow: autoexec install/sync/verification, unified status, rba_git_status, and rba_git_sync_files
Use tools/list from the MCP client for the authoritative schema and descriptions.
The repository also preserves the development scripts created alongside RBA, including the goalkeeper, solo-player, Chicken Farm, and Luarmor analysis helpers under lua/. They remain source-visible for rollback and continued local work, but they are not part of the RBA runtime, are not included in the npm package, and must only be used in environments you own or are authorized to test.
Keeping them outside the published package gives the Git repository a complete project history without making experience-specific experiments part of the bridge's supported API.
Websocket and dashboard hosts default to 127.0.0.1.
Workspace file tools reject traversal outside RBA_ROOT.
Instance Manager probes and loader overrides accept loopback addresses only.
Payload size, rate, buffered-byte, event-memory, log-file, and evaluation limits are bounded.
Git sync requires explicit file paths, refuses a pre-staged index, and never uses git add --all.
Roblox restart discovers and validates RobloxPlayerBeta.exe, then stops only processes with that exact executable name.
Autoexec replacement makes a backup before overwriting changed content.
npm run dev
npm run build
npm test
npm pack --dry-runThe test suite compiles TypeScript, parses the full Luau loader, validates lifecycle and protocol guardrails, exercises normal and oversized websocket traffic, verifies autoexec synchronization, and smoke-tests capsule creation and snapshots through MCP.
Architecture notes live in docs/ARCHITECTURE.md. Security reports should follow SECURITY.md.
MIT. See LICENSE.
Prepare RBA for an agent session: start or attach the bridge, sync autoexec, optionally start dashboard, notify clients, and return health.
Inputs: notify, timeoutMs, includePing, dashboardPort, +1 more.
Append text to a file inside the RBA workspace, creating it when needed.
Inputs: path (required), content (required), createDirectories.
Show every configured executor autoexec target and verify its installed loader hash against the workspace source.
Inputs: no named parameters.
Create a timestamped backup of a workspace file under .rba-backups.
Inputs: path (required), reason.
Run multiple workspace file operations in one call.
Inputs: operations (required).
Create a source snapshot for one script capsule. Use it as a time-travel restore point before an edit or experiment.
Inputs: id (required), reason.
Capture RobloxPlayerBeta.exe and return the screenshot as an MCP image for visual context.
Inputs: outputPath, focusWindow, includeImage.
Capture a screenshot of a visible Windows process window and return it as an MCP image.
Inputs: processName (required), outputPath, focusWindow, includeImage.
Clear buffered RBA events, optionally only those matching type/client filters.
Inputs: type, clientId.
Show full details for one connected RBA websocket client.
Inputs: clientId (required).
List connected RBA websocket clients.
Inputs: no named parameters.
Return the active RBA websocket host, port, URL, candidate URLs, and published connection-state checks.
Inputs: no named parameters.
Capture status, clients, recent events, runtime summary, and optional Roblox screenshot in one call.
Inputs: target, timeoutMs, eventLimit, focusWindow, +2 more.
Create a named RBA script capsule: a permission-gated policy envelope around one workspace Lua file. Capsules preflight and snapshot source before dispatch; they do not claim to OS-sandbox code inside a Roblox executor.
Inputs: id (required), name (required), path (required), permissions.
Start the local RBA dashboard HTTP server.
Inputs: host, port.
Stop the local RBA dashboard HTTP server.
Inputs: no named parameters.
Read-only Roblox process and RBA heartbeat diagnosis. Reports healthy, bridge_disconnected, not_running, or likely_crashed without changing any process.
Inputs: target, timeoutMs, includePing, staleAfterMs.
One development-oriented snapshot: RBA health, Roblox crash likelihood, autoexec state, and optional static script preflight. Does not execute the inspected script.
Inputs: target, timeoutMs, scriptPath, includePing, +1 more.
Close one connected RBA websocket client.
Inputs: clientId (required).
Run Lua and wait for structured return values or errors from connected clients.
Inputs: script (required), label, target, timeoutMs.
Run a workspace Lua file and wait for structured return values or errors from connected clients.
Inputs: path (required), label, target, timeoutMs.
Read recent websocket/client events captured by RBA.
Inputs: type, limit, since, until, +1 more.
Execute multiple workspace Lua files in order with syntax checks, optional delay, and stop-on-error control.
Inputs: files (required), mode, target, delayMs, +3 more.
Execute a workspace Lua file in Roblox, either fire-and-forget send or eval with structured results.
Inputs: path (required), mode, label, target, +2 more.
Show the current RBA autorun-on-connect configuration.
Inputs: no named parameters.
Return the local character position and CFrame from connected development clients.
Inputs: target, timeoutMs.
Inspect the RBA workspace Git repository, selected branch/origin, changed and staged files, and the exact autoloader fingerprint without changing Git state.
Inputs: no named parameters.
Explicitly commit selected existing RBA workspace files and optionally push the current branch. It refuses to run with a pre-staged index and never uses git add --all, so unrelated scripts are not swept into a sync.
Inputs: files (required), message (required), push, branch, +1 more.
Diagnose the shared RBA bridge, Instance Manager endpoint, connected clients, autoexec targets, recent errors, and optional eval/ping health.
Inputs: timeoutMs, includePing.
Install the current RBA autoloader into an executor autoexec path, backing up any existing file first.
Inputs: sourcePath, targetPath.
Mirror client print/warn output back to RBA events with a Roblox-safe rate limit.
Inputs: target, timeoutMs, maxPerSecond.
Install debug helpers on connected clients and return an initial runtime snapshot.
Inputs: target, timeoutMs.
List sidecar backups created for an autoexec target.
Inputs: targetPath.
List workspace file backups, optionally filtered to one original path.
Inputs: path.
List time-travel source snapshots for one RBA script capsule.
Inputs: id (required).
List files inside the RBA workspace.
Inputs: path, recursive, maxEntries.
List built-in Lua websocket presets.
Inputs: no named parameters.
List registered script capsules and their explicit permissions, source file, timestamps, and policy-sandbox limitation.
Inputs: no named parameters.
List script profiles from the workspace profile JSON file.
Inputs: no named parameters.
List active RBA file watchers.
Inputs: no named parameters.
List visible desktop windows that can be used as screenshot targets.
Inputs: no named parameters.
Run local Lua syntax validation with luac for a workspace file or provided source before sending to Roblox.
Inputs: path, source.
Show an in-game RBA notification on connected Roblox clients.
Inputs: message (required), level, title, target, +1 more.
Ping connected clients and return round-trip timing plus basic place/job details.
Inputs: target, timeoutMs.
Run a built-in realtime probe such as summary, character, camera, players, environment, or datamodel.
Inputs: probe (required), target, timeoutMs.
Read a workspace file, capped to a safe byte limit.
Inputs: path (required), maxBytes.
Read a workspace PNG/JPEG file and return it as an MCP image.
Inputs: path (required).
Safely restart RobloxPlayerBeta.exe: discover and verify the current/installed executable path, close only RobloxPlayerBeta processes, then launch the verified executable normally.
Inputs: closeAll, restartDelayMs, waitForProcessMs.
Restore an autoexec sidecar backup and preserve the currently installed file first.
Inputs: backupPath (required), targetPath.
Restore a .rba-backups file, first backing up the current destination when it exists.
Inputs: backupPath (required), destinationPath.
Return the local character to its position before the most recent RBA teleport.
Inputs: target, timeoutMs.
Restore a capsule source file from a selected snapshot. RBA captures the current source first as a safety snapshot.
Inputs: id (required), snapshotId (required).
Run a built-in Lua preset on connected development clients.
Inputs: preset (required), target.
Preflight, permission-check, optionally snapshot, and then dispatch a script capsule. Missing required permissions block the run before any Lua reaches a client.
Inputs: id (required), mode, target, timeoutMs, +2 more.
Run a named script profile from the workspace profile JSON file.
Inputs: name (required), target.
Statically inspect a workspace Lua file or provided source before execution: syntax, metrics, lifecycle/loop checks, dynamic loading, remote calls, and direct transform writes. Never executes the script.
Inputs: path, source.
Search text files inside the RBA workspace.
Inputs: query (required), path, extensions, maxResults.
Set the default client used when a tool target is omitted.
Inputs: clientId (required).
Send Lua source text to connected development clients through the websocket bridge.
Inputs: script (required), target.
Send a Lua file from the RBA workspace to connected development clients.
Inputs: path (required), target.
Configure optional profile/file execution that runs automatically when a Roblox client connects.
Inputs: mode, files, target, enabled, +2 more.
Update the in-game RBA status panel on connected Roblox clients.
Inputs: message (required), level, target.
Replace a script capsule's explicit capability grants. The next capsule run is blocked when static source requirements are not granted.
Inputs: id (required), permissions (required).
Watch multiple workspace Lua files as one live-editing session and optionally run them once immediately.
Inputs: files (required), mode, target, runOnce, +3 more.
Stop every active RBA live-edit file watcher.
Inputs: no named parameters.
Sync the same unified RBA and Roblox Instance Manager autoloader to every configured executor target.
Inputs: backupExisting.
Sync the workspace unified autoloader to one autoexec target, backing up changed content by default.
Inputs: targetPath, backupExisting.
Teleport the local character to a Workspace BasePart or Model path, with an optional local offset.
Inputs: partPath (required), target, offsetX, offsetY, +3 more.
Teleport the local player to a Roblox place, optionally joining a specific public server job.
Inputs: placeId (required), jobId, target, timeoutMs.
Teleport the local character to exact coordinates and remember the previous position.
Inputs: x (required), y (required), z (required), target, +2 more.
Verify the complete local workflow: RBA websocket service, Instance Manager connector endpoint, and every executor autoexec copy.
Inputs: timeoutMs.
Restore print/warn after rba_install_console_mirror.
Inputs: target, timeoutMs.
Stop one active RBA file watcher.
Inputs: id (required).
Wait briefly for the next websocket event, optionally filtered by type and client id.
Inputs: type, clientId, timeoutMs.
Watch a workspace Lua file and auto-send or eval it in Roblox on change for live editing.
Inputs: path (required), mode, target, timeoutMs, +2 more.
Create or replace a file inside the RBA workspace.
Inputs: path (required), content (required), overwrite, backupExisting, +1 more.
Start the local RBA websocket bridge used by the Lua autoloader.
Inputs: host, port.
Show websocket bridge status, connected clients, and recent client events.
Inputs: no named parameters.
Stop the local RBA websocket bridge.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 79 tools
Many tools have overlapping purposes, especially the status/snapshot cluster (rba_health_check, rba_unified_status, rba_development_snapshot, rba_context_snapshot, rba_connection_info, rba_ws_status) which all provide similar diagnostic information. Execution tools (rba_send_lua, rba_eval_lua, rba_execute_file, rba_eval_lua_file) also blur boundaries between send, eval, and execute.
Tools use a consistent rba_ prefix and snake_case, but verb usage is inconsistent: some are verb_noun (rba_start_live_session, rba_list_files), while others are noun-only (rba_events, rba_clients) or noun_noun (rba_connection_info, rba_health_check). This mix reduces predictability.
With 79 tools, the set is far too large for most workflows. While the domain is complex, many functions could be consolidated (e.g., multiple snapshot/status tools into one, or combined file operations). This exceeds the typical well-scoped range and adds cognitive overhead.
The tool set provides extensive coverage of the Roblox bridge development lifecycle: connection management, Lua execution, file operations, autoexec configuration, script capsules, watchers, teleportation, screenshots, and debugging. There are no obvious dead ends, and generic eval_lua covers arbitrary Roblox interactions.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
