> ## Content Index > Fetch the complete content index at: https://openbeam.world/llms.txt > Use this file to discover other available public pages before exploring further. # OpenBeam MCP tools - URL: https://openbeam.world/docs/openbeam-mcp-tools/ - Published: 2026-09-29T22:30:03.000Z - Updated: 2026-09-29T22:30:03.000Z - Author: Beshoy Hanna - Tags: #docs 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](mcp-access.md) 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](#status) | Inspect the simulation, vehicles, menus, and operation state. | | [telemetry](#telemetry) | Read the current player vehicle's motion and physics summary. | | [screenshot](#screenshot) | Capture the game window. | | [read\_log](#read%5Flog) | Read recent game or script log messages. | | [list\_levels](#list%5Flevels) | Find level archives available to the game. | | [upload\_level](#upload%5Flevel) | Install a level archive into the session. | | [delete\_level](#delete%5Flevel) | Remove an uploaded level archive from the session. | | [install\_mod](#install%5Fmod) | Install a vehicle mod, level archive, or combined archive. | | [list\_mods](#list%5Fmods) | Inspect uploaded mods and their usable vehicles. | | [delete\_mod](#delete%5Fmod) | Remove an uploaded mod archive from the session. | | [load\_level](#load%5Flevel) | Load an installed level or classic terrain. | | [spawn\_vehicle](#spawn%5Fvehicle) | Spawn a vehicle in the loaded level. | | [reload](#reload) | Apply texture or level changes while the game runs. | | [asset\_zone](#asset%5Fzone) | Show the area where an agent is creating or updating an asset. | | [run\_script](#run%5Fscript) | Execute an AngelScript statement. | | [gamepad](#gamepad) | Operate game menus through simulated controller input. | | [quit](#quit) | Request that the game exit. | | [cloud\_status](#cloud%5Fstatus) | Inspect the game's Cloud account sign-in. | | [cloud\_sign\_in](#cloud%5Fsign%5Fin) | Sign the game into an OpenBeam Cloud account. | | [cloud\_sign\_out](#cloud%5Fsign%5Fout) | Clear the game's saved Cloud sign-in. | | [cloud\_list\_levels](#cloud%5Flist%5Flevels) | List the account's Cloud library. | | [cloud\_upload\_level](#cloud%5Fupload%5Flevel) | 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: ```json { "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: ```json {"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`. ```json {"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. ```json {"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. ```json {"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. ```json {"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//` directory. A vehicle mod supplies a `vehicles//` 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. ```json {"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](#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`. ```json {"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. ```json {"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](#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. ```json {"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`. ```json {"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. ```json {"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. ```json {"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. ```json {"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.` for an increased count, `applied`, and `outcome`. A queued reply confirms the request was accepted; the later reload result reports whether it was applied. ```json {"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: ```json {"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: ```json {"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`. ```json {"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. ```json {"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. ```json {"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](mcp-access.md). ### `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 reports `phase` and `message`; while waiting, it also includes `user_code`, `verification_uri`, `verification_uri_complete`, and `seconds_left`. Credential-file problems can appear in `problem`. The saved token is never returned. ```json {"name":"cloud_status","arguments":{}} ``` ### `cloud_sign_in` Sign the running game into an OpenBeam Cloud account. | Argument | Type | Required | Meaning | | -------- | ------ | -------- | --------------------------------------------------------------------------------------- | | token | string | No | An already-issued Cloud user token. If omitted, start device approval. | | api\_url | string | No | Override the Cloud service address. The public service is https://cloud.openbeam.world. | **Returns:** for device approval, `status`, `api_url`, `user_code`, `verification_uri`, `verification_uri_complete`, `expires_in`, and a message. Open the complete approval link, sign in, and approve the matching code. The game polls and stores its sign-in automatically. With an existing token, a successful call reports `signed_in: true` and the account details available to the game. ```json {"name":"cloud_sign_in","arguments":{}} ``` Use `cloud_status` to check completion. Tokens are checked before saving and kept in the game's private configuration, not returned by these tools. ### `cloud_sign_out` Cancel device sign-in in progress and forget the game's saved Cloud credentials. **Arguments:** none. **Returns:** `signed_in: false`. ```json {"name":"cloud_sign_out","arguments":{}} ``` This clears the game's local sign-in. It does not sign the browser out or revoke tokens issued to other clients. ### `cloud_list_levels` List the signed-in account's Cloud library, including level archives and vehicle mods. The game must have completed `cloud_sign_in` first. **Arguments:** none. **Returns:** `api_url` and a `levels` array. Each record includes `id`, `filename`, `sha256`, `size`, `levelIds`, `vehicleIds`, and `createdAt`. ```json {"name":"cloud_list_levels","arguments":{}} ``` ### `cloud_upload_level` Upload a level archive or vehicle mod from the game's machine to the signed-in account's Cloud library. | Argument | Type | Required | Meaning | | ----------- | ------ | ---------- | ----------------------------------------------------------------------------------------------- | | level\_id | string | One source | A level ID reported by list\_levels. | | vehicle\_id | string | One source | A vehicle ID in an uploaded mod reported by list\_mods. | | path | string | One source | A ZIP archive on the game's machine. | | filename | string | No | Select an archive when several uploaded archives contain the chosen level or vehicle ID. | | upload\_as | string | No | Filename to use in the Cloud library. Defaults to the archive's own name, sanitized for upload. | Supply exactly one of `level_id`, `vehicle_id`, or `path`. A `vehicle_id` source must identify an uploaded vehicle mod; use `path` for another local archive. `upload_as` follows the archive filename rules described above. **Returns:** `outcome`, either `created` or `already_uploaded`, and the Cloud archive record under `level`. Identical archive bytes already in the library count as success. ```json {"name":"cloud_upload_level","arguments":{"level_id":"YOUR_LEVEL_ID","filename":"example-level.zip","upload_as":"example-level.zip"}} ``` The game needs a completed Cloud sign-in and an account with active Cloud access. Saving an archive to the library does not load it into another running simulation. ## Typical workflows ### Load a level and inspect a vehicle 1. Call `status` to inspect the current session. 2. Call `upload_level` for a level archive, or `list_levels` to use one already available. 3. Call `load_level` with a returned level ID and an explicit wait time. Confirm `loaded: true`. 4. Call `install_mod` for a vehicle archive, or `list_mods` to find an installed vehicle. 5. Call `spawn_vehicle` with an exact filename from `vehicles`. Confirm `spawned: true`. 6. Call `telemetry` and `screenshot` to inspect the result. ### Run a test and inspect what happened 1. Prepare the level and vehicle, then call `status`. 2. Call `run_script` with the AngelScript test statement. 3. Check `succeeded` and call `read_log` with `log: "script"`. 4. Read `telemetry` or capture a `screenshot` as appropriate for your test. ### Save an archive to the Cloud library 1. Call `cloud_status`. 2. If needed, call `cloud_sign_in`, approve the returned device code, and wait for `cloud_status` to report `signed_in: true`. 3. Call `cloud_upload_level` with one archive source. 4. Call `cloud_list_levels` to confirm the saved archive. ## Handling errors - Check the MCP tool result's `isError`, any `structuredContent.error` and `message`, and the tool's completion fields. - Use `read_log` to investigate failed loads, spawns, scripts, or captures. - For `pending: true`, poll `status` before repeating a state-changing request. - `not_signed_in` from a Cloud library tool means the game needs `cloud_sign_in`. - If a Cloud request returns `unauthorized`, complete a new Cloud sign-in. An account without active access can receive `not_entitled`. - HTTP authentication, expired device-code, and session-connection errors are covered in [MCP access troubleshooting](mcp-access.md#troubleshooting).