OpenBeam MCP tools

This reference covers the 22 tools exposed by the OpenBeam game's MCP server. Through OpenBeam Cloud, they operate on the game in the session you connected to. Follow MCP access and connection to connect a client.

Use your connected server's tools/list response to confirm the names and input schemas available in your session. Game versions can differ.

Tool index

Tool	Purpose
`status`	Inspect the simulation, vehicles, menus, and operation state.
`telemetry`	Read the current player vehicle's motion and physics summary.
`screenshot`	Capture the game window.
`read_log`	Read recent game or script log messages.
`list_levels`	Find level archives available to the game.
`upload_level`	Install a level archive into the session.
`delete_level`	Remove an uploaded level archive from the session.
`install_mod`	Install a vehicle mod, level archive, or combined archive.
`list_mods`	Inspect uploaded mods and their usable vehicles.
`delete_mod`	Remove an uploaded mod archive from the session.
`load_level`	Load an installed level or classic terrain.
`spawn_vehicle`	Spawn a vehicle in the loaded level.
`reload`	Apply texture or level changes while the game runs.
`asset_zone`	Show the area where an agent is creating or updating an asset.
`run_script`	Execute an AngelScript statement.
`gamepad`	Operate game menus through simulated controller input.
`quit`	Request that the game exit.
`cloud_status`	Inspect the game's Cloud account sign-in.
`cloud_sign_in`	Sign the game into an OpenBeam Cloud account.
`cloud_sign_out`	Clear the game's saved Cloud sign-in.
`cloud_list_levels`	List the account's Cloud library.
`cloud_upload_level`	Save a level or vehicle archive to the Cloud library.

Calling a tool

Most MCP clients let you call a tool by name and supply its arguments. Over HTTP, a tool call uses a JSON-RPC request like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "status",
    "arguments": {}
  }
}

The examples in each tool entry below show the params object. Tools with no arguments use {}. Supply only the documented argument names; the schemas disallow additional properties.

To discover the tools, send a tools/list request through your MCP client:

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

Files and coordinates

path, archive, and returned file paths refer to files on the machine running the game. In a hosted session, that is the game server. To install an archive from a URL, supply a URL the game can download and the archive's SHA-256 digest.

Positions and asset-zone bounds use three numbers, [x, y, z], in world metres, with positive Y pointing up.

Reading results

Tool results can include text, structuredContent, or image content. Check isError and any completion fields such as loaded, spawned, or succeeded. A queued or pending operation needs a later check before you treat it as finished.

For operations that report queued_at_frame, status.serviced_frames advancing beyond that frame with status.queue_empty: true indicates that queued work has been serviced. Use read_log to investigate a refusal.

State and diagnostics

`status`

Read the current game state. Call this first when working with a session.

Arguments: none.

Returns: app_state, sim_state, terrain, terrain_loaded, actor_count, and player_actor (or null). It also reports menu visibility in menus, operation progress through serviced_frames and queue_empty, cache_refresh_pending, hot-reload results in reloads, and current asset_zones.

{"name":"status","arguments":{}}

`telemetry`

Read a physics summary for the vehicle the player is currently using. Spawn and enter a vehicle first.

Arguments: none.

Returns: vehicle name, position, velocity, speed_mps, wheel_speed_mps, nodes, beams, and broken_beams. engine_rpm and gear are included when the vehicle has an engine. A session with no player vehicle returns a tool error.

{"name":"telemetry","arguments":{}}

`screenshot`

Capture the presented game window.

Argument	Type	Required	Meaning
`wait_seconds`	number	No	Time to wait for the capture, from 1 to 120 seconds. Default: 20.

Returns: image content when the capture fits the inline size limit, plus metadata containing path, bytes, and inline. Larger captures return the game-server file path and inline: false. A returned server path is not a public download URL.

{"name":"screenshot","arguments":{"wait_seconds":20}}

`read_log`

Read the tail of the game log or script log, optionally filtering the lines.

Argument	Type	Required	Meaning
`log`	string	No	`game` (default) or `script`.
`lines`	integer	No	Number of matching lines to return, from 1 to 2000. Default: 100.
`grep`	string	No	Regular expression used to filter messages.

Returns: log text. The game log is RoR.log; the script log is Angelscript.log. Filtering uses ECMAScript regular expressions.

{"name":"read_log","arguments":{"log":"game","lines":100,"grep":"Spawn|refus|JBeam"}}

Levels, vehicles, and asset updates

Archive arguments

upload_level and install_mod accept the same arguments:

Argument	Type	Required	Meaning
`url`	string	One source	HTTP or HTTPS URL of a ZIP archive. Supply exactly one of `url` or `path`.
`path`	string	One source	ZIP archive already on the game's machine.
`sha256`	string	With `url`	Expected SHA-256 digest: 64 hexadecimal characters. It can also verify a local file.
`filename`	string	No	Installed archive name, ending in `.zip`.
`replace`	boolean	No	Allow replacement of an archive with the same installed name. Default: false.

Archive filenames must be 1–128 bytes, contain only letters, numbers, ., _, spaces, or -, and end in .zip. If filename is omitted, the tool derives it from the source name or digest.

An archive supplies a level through a levels/<level_id>/ directory. A vehicle mod supplies a vehicles/<vehicle_id>/ directory containing .jbeam or .pc files. The returned cache results identify which vehicles are usable.

`list_levels`

List uploaded level archives and level archives known to the game's mod cache.

Arguments: none.

Returns: a levels array and upload_directory. Archive records include filename, path, size, sha256 (which may be null), levelIds, vehicleIds, and uploaded. Cached level details can include display names and spawn points. A cache lookup problem is reported in cache_error when applicable.

{"name":"list_levels","arguments":{}}

`upload_level`

Install a ZIP archive containing a BeamNG level into the session. Use load_level afterward to enter one of its levels.

Arguments: exactly one of url or path, plus sha256, filename, and replace as described in Archive arguments. A URL requires sha256.

Returns: the installed archive under level, already_present, and the cache refresh result in cache. Cache information can include entries, vehicles, and refused. The archive's levelIds are the IDs to use with load_level.

{"name":"upload_level","arguments":{"url":"https://example.com/example-level.zip","sha256":"YOUR_ARCHIVE_SHA256","filename":"example-level.zip"}}

Replace the example URL and digest with values for your archive. Installing an archive and loading its level are separate operations.

`delete_level`

Remove an archive from the session's uploaded archive folder and refresh its cache entries.

Argument	Type	Required	Meaning
`filename`	string	Yes	Name of an uploaded ZIP archive, as returned by the listing tools.

Returns: deleted with the filename and cache with the refresh outcome. Only archives in the uploaded folder can be removed. The Cloud library is separate from the session's files.

{"name":"delete_level","arguments":{"filename":"example-level.zip"}}

`install_mod`

Install a vehicle mod, a level archive, or a ZIP containing both. The game refreshes the mod cache, including while a level is loaded.

Arguments: exactly one of url or path, plus sha256, filename, and replace as described in Archive arguments. A URL requires sha256.

Returns: the installed archive under mod, already_present, and cache. When available, vehicles contains the exact filenames accepted by spawn_vehicle; entries contains cache entries, and refused lists rejected entries and their causes.

{"name":"install_mod","arguments":{"url":"https://example.com/example-vehicle.zip","sha256":"YOUR_ARCHIVE_SHA256","filename":"example-vehicle.zip"}}

Copy a filename from the returned vehicles list when spawning a vehicle. The game's cache names can differ from the ZIP filename.

`list_mods`

List the session's uploaded archives and the cache contents associated with them.

Arguments: none.

Returns: a mods array and upload_directory. Records include archive metadata, levelIds, and vehicleIds; available cache details include vehicles, entries, and refused.

{"name":"list_mods","arguments":{}}

`delete_mod`

Remove an uploaded archive containing a vehicle mod, level, or both. It uses the same removal behavior as delete_level.

Argument	Type	Required	Meaning
`filename`	string	Yes	Name of an uploaded ZIP archive.

Returns: deleted with the filename and cache with the refresh outcome. Removing a session archive does not delete a copy in the Cloud library.

{"name":"delete_mod","arguments":{"filename":"example-vehicle.zip"}}

`load_level`

Leave the current level and load an installed BeamNG level or a classic terrain.

Argument	Type	Required	Meaning
`level_id`	string	For a BeamNG level	An ID returned by `list_levels`, `upload_level`, or `install_mod`.
`filename`	string	No	Choose a particular installed archive when several contain the same `level_id`.
`archive`	string	No	Explicit archive path on the game's machine, used with `level_id`.
`sha256`	string	No	Digest for the archive. The game can use a known digest or compute one if omitted.
`terrain`	string	For a classic terrain	Terrain name. Use this instead of `level_id` and `archive`.
`spawn`	string	No	Named spawn point for a BeamNG level.
`wait_seconds`	number	No	Time to wait for completion, from 0 to 900 seconds. Zero returns after queuing the load.

Returns: requested, and sha256 for archive loads. A completed load reports loaded and terrain. A load still in progress reports loaded: false and pending: true; a zero wait reports queued: true. A refused load is a tool error with a message.

{"name":"load_level","arguments":{"level_id":"YOUR_LEVEL_ID","filename":"example-level.zip","wait_seconds":180}}

Set wait_seconds explicitly for a predictable wait across game versions. If loading remains pending, poll status and inspect read_log before requesting another load.

`spawn_vehicle`

Spawn a vehicle from the mod cache. A level must already be loaded.

Argument	Type	Required	Meaning
`file`	string	Yes	Exact vehicle filename from the cache, such as an entry returned by `install_mod` or `list_mods`.
`config`	string	No	A configuration offered by that vehicle. The game selects an available configuration when omitted.
`position`	array of 3 numbers	No	Spawn position `[x, y, z]` in world metres. Defaults to the player's character position when available.
`enter`	boolean	No	Enter the spawned vehicle when it can be driven. Default: true.
`wait_seconds`	number	No	Time to wait, from 0 to 600 seconds. Zero returns after queuing the spawn.

Returns: resolved and config. A completed attempt includes spawned, actor_count, and player_actor when available. An incomplete wait reports spawned: false and pending: true; zero wait reports queued: true. A completed attempt that creates no actor is a tool error.

{"name":"spawn_vehicle","arguments":{"file":"VEHICLE_FILENAME_FROM_LIST_MODS","enter":true,"wait_seconds":60}}

Set wait_seconds explicitly. Read telemetry after spawning and entering a vehicle to inspect its physics summary.

`reload`

Apply changed texture packs or changes to the loaded BeamNG level while the game runs.

Argument	Type	Required	Meaning
`what`	string	Yes	`textures` or `level`.

Returns: queued and count_before. Poll status.reloads.<what> for an increased count, applied, and outcome. A queued reply confirms the request was accepted; the later reload result reports whether it was applied.

{"name":"reload","arguments":{"what":"level"}}

`asset_zone`

Show an agent's work area as a box in the world with a status marker. Use it to communicate progress while creating or changing content.

Argument	Type	Required	Meaning
`action`	string	Yes	`begin`, `update`, `end`, `remove`, or `list`.
`key`	string	Except for `list`	Stable identifier for the zone.
`label`	string	No	Name shown to the user.
`state`	string	No	`pending` or `building` while work is active. The default for a new zone is `building`.
`progress`	number	No	Progress from 0 to 1.
`message`	string	No	Progress details or the final result message.
`box`	object	No	Bounds with `min` and `max`, each `[x, y, z]`.
`center`	array of 3 numbers	With `size`	Alternative to `box`: the box centre.
`size`	array of 3 numbers	With `center`	Non-negative box dimensions in metres.
`result`	string	For `end`	`ready` or `failed`.

Returns: zone for begin, update, or end; zones for list; or removed: true for removal. Zones also appear in status.asset_zones.

Begin a zone:

{"name":"asset_zone","arguments":{"action":"begin","key":"example-asset","label":"Example asset","center":[0,2,0],"size":[10,4,10],"state":"building","progress":0}}

Finish it:

{"name":"asset_zone","arguments":{"action":"end","key":"example-asset","result":"ready","message":"Asset is ready"}}

Use update with the same key to change progress or geometry. Use either box or the paired center and size. Keys beginning with level:, overlay:, or content: are reserved for the game's own zones. Completed zones fade; a zone with no updates for 15 minutes is marked as stalled.

Scripts and controls

`run_script`

Execute one AngelScript statement in the game.

Argument	Type	Required	Meaning
`code`	string	Yes	A non-empty AngelScript statement.

Returns: return_code and succeeded. Read the script log for messages or errors. An unsuccessful script can return succeeded: false, so check this field as well as the MCP result's isError.

{"name":"run_script","arguments":{"code":"game.log(\"Example test message\");"}}

Follow with read_log using log: "script" to inspect the output.

`gamepad`

Send controller input to the game's menus. The D-pad and left stick move focus; a selects, b goes back, and lb or rb switches tabs. In a simulation, menu opens the pause menu. This tool operates menus; vehicle driving is not implemented by this tool.

Argument	Type	Required	Meaning
`button`	string	For a button press	`a`, `b`, `x`, `y`, `view`, `menu`, `ls`, `rs`, `lb`, `rb`, `up`, `down`, `left`, or `right`.
`action`	string	No	`tap` (default), `down`, or `up`.
`axis`	string	For axis input	`left_x`, `left_y`, `right_x`, `right_y`, `lt`, or `rt`.
`value`	number	With `axis`	Stick value from -1 to 1; use 0 to release. Trigger controls conventionally use 0 to 1.

Returns: the button and action, or axis and value, plus queued_at_frame. Use status.menus to confirm the resulting screen.

{"name":"gamepad","arguments":{"button":"a","action":"tap"}}

Send one button action or one axis value per call. After a held button (down), send up to release it. A non-zero axis value stays active until you send another value, typically 0.

`quit`

Request that the game exit. The MCP connection can become unavailable once it shuts down.

Arguments: none.

Returns: queued: true when shutdown has been requested.

{"name":"quit","arguments":{}}

Cloud account and library

These tools manage the running game's own sign-in to OpenBeam Cloud and its access to the account's stored archives. Connecting an external MCP client to a hosted session uses the separate MCP access flow.

`cloud_status`

Inspect whether the game has a saved Cloud sign-in and whether device approval is in progress.

Arguments: none.

Returns: signed_in, api_url, and user_id when available. A sign_in object