Debugging Live Roblox Game Logic with MCP Runtime Tools

Runtime debugging with Roblox Studio MCP means you can inspect and instrument a live game session without ever pausing it. By combining eval_server_runtime, log-breakpoints, get_runtime_logs, and capture_script_profiler, an agent can trace a bug from its first symptom—an unexpected value returned from the server—all the way down to the specific function consuming the most CPU, then apply a surgical fix and verify the result in the same session.

Full debug workflow

Start a playtest

Begin a solo playtest in Play mode. This launches the server and client peers and activates the runtime eval bridges inside the play DataModel.

solo_playtest action="start" mode="play"

Evaluate live state on the server

Use eval_server_runtime to inspect any server-side value while the game is running. This executes in the game Script VM and shares the same require cache as your game scripts, so module-level singletons are visible.

-- Example: read a service value live
return SomeService.someValue

Call it as:

eval_server_runtime code="return SomeService.someValue"

eval_server_runtime runs inside the running game’s Script VM, giving it access to the same require cache as your game scripts. execute_luau target="server" runs in the plugin context with PluginSecurity permissions instead — it sees the live DataModel but does not share the game’s require cache. Use eval_server_runtime when you need to call into your own module singletons.

Set a log breakpoint on the suspected function

Log breakpoints are the recommended agent debugging primitive. They print diagnostic output into the log buffer without stopping the playtest. Set the breakpoint on the line inside the function you want to instrument, providing a log_message expression.

breakpoints action="set"
           script_path="game.ServerScriptService.RoundManager"
           line=42
           log_message="'damage called, health=', health, 'attacker=', attacker"
           continue_execution=true
           target="server"

The tool prefixes all breakpoint log lines with "Breakpoint" followed by the script path and line number, making them easy to filter later.

Reproduce the bug

Trigger the code path that contains the suspected bug. You can use input simulation tools to drive the game without manual intervention:

# Click a button in the game UI
simulate_mouse_input action="click" x=640 y=360

# Or press a key to trigger a player action
simulate_keyboard_input keyCode="E" action="tap"

Alternatively, use eval_server_runtime to call the buggy function directly:

eval_server_runtime code="RoundManager:startRound()"

Read the breakpoint logs

After reproducing the behavior, read the runtime log buffer and filter by "Breakpoint" to isolate only the breakpoint output. This filter also catches any breakpoint-related Studio errors.

get_runtime_logs filter="Breakpoint"

In a standard solo playtest, LogService reflects logs across all peers, so you will see breakpoint output regardless of which target you read from. Use target="all" to merge all buffers.

Profile if needed

If the breakpoint logs point to a hot code path, capture a Script Profiler sample to get precise CPU timing. Trigger the relevant workload first, then capture while it is running.

capture_script_profiler target="server" duration_ms=2000

The result includes top_functions sorted by descending total_us. Look for your game module functions at the top of the list — native and plugin frames are excluded by default.

Identify and label the hotspot

Identify the hottest function from top_functions. If function names are too broad to isolate the specific culprit, add debug.profilebegin / debug.profileend labels around the suspected code path, then re-capture with a filter matching the label prefix.

-- Add in the hot function:
debug.profilebegin("RoundManager:processDamage")
-- ... existing code ...
debug.profileend()

Then re-capture with the same duration and a label filter:

capture_script_profiler target="server"
                        duration_ms=2000
                        filter="RoundManager:"

Custom debug.profilebegin labels appear in both debug_labels and top_functions with their script source.

Keep duration_ms short (1000–2000 ms) and make sure the workload you care about is actively running during the capture window. A 2-second capture while the server idles produces unhelpful results.

Fix the script

Apply the fix using edit_script_lines for surgical changes or set_script_source for a full rewrite. edit_script_lines requires old_string to match exactly once in the script; supply line_range to anchor it when the string appears more than once.

# Surgical fix — replace one statement
edit_script_lines instancePath="game.ServerScriptService.RoundManager"
                  old_string="if health <= 0 then killPlayer() end"
                  new_string="if health <= 0 then killPlayer(attacker) end"

# Full rewrite
set_script_source instancePath="game.ServerScriptService.RoundManager"
                  source="..."

Before writing fix code, use get_roblox_docs to verify API signatures, method names, and parameter types. Roblox’s API surface changes across engine versions and relying on memorized signatures can introduce new bugs.

Stop the playtest

Stop the playtest once you have applied the fix.

solo_playtest action="stop"

Re-run to verify

Start a fresh playtest and reproduce the same scenario to confirm the fix works correctly. Re-read get_runtime_logs to verify the breakpoint output shows the corrected behavior.

solo_playtest action="start" mode="play"
eval_server_runtime code="return RoundManager.lastRoundResult"
get_runtime_logs filter="Breakpoint"

Clear the MCP-managed breakpoints once you are satisfied:

breakpoints action="clear" target="server"

Example: finding why a round never starts

A common real-world scenario for this workflow is diagnosing a game where rounds fail to begin. You can give an agent a prompt like:

“Start a multiplayer test with 2 clients, read the server log, and tell me why the round never starts.”

The agent will:

Start a multiplayer playtest with multiplayer_playtest action="start" numPlayers=2 force=true
Read get_runtime_logs target="server" to look for error output or missing expected log lines
Use eval_server_runtime to inspect RoundService.state or whatever holds the round lifecycle state
Set a log breakpoint on the round-start function to observe what values it receives when called
Report back what condition is preventing the round from proceeding

The combination of live eval and log breakpoints makes it possible to observe the exact state at the moment the logic fails, rather than reconstructing it from static code inspection alone.

execute_luau vs eval_server_runtime

Both tools can run code on the server peer during a playtest, but they operate in different contexts.

Tool	VM context	require cache	Use when
`eval_server_runtime`	Game Script VM	Shared with game scripts	Calling into game module singletons, reading live service state
`execute_luau target="server"`	Plugin context (PluginSecurity)	Separate from game scripts	Studio API calls, bypassing game security boundaries

If you receive a generic "Requested module experienced an error while loading" message from eval_server_runtime, the error is Roblox’s require() wrapper — the actual error text is preserved inside the message. Read it carefully rather than retrying blindly.

Workflows

Reference

Debugging Live Roblox Game Logic with MCP Runtime Tools

Full debug workflow

Example: finding why a round never starts

execute_luau vs eval_server_runtime

Build docs developers (and LLMs) love

Workflows

Reference

Documentation Index

​Full debug workflow

​Example: finding why a round never starts

​execute_luau vs eval_server_runtime

Build docs developers (and LLMs) love

Full debug workflow

Example: finding why a round never starts

execute_luau vs eval_server_runtime