MCP tool reference

Read this page as Markdown · All docs for AI agents

All tools operate on the world selected by your credential and its owner's asset library. Tool success includes structuredContent plus equivalent JSON text. Tool failure uses isError: true; inspect the returned message even when HTTP itself succeeded.

world_download

Input: {}.

Returns worldId, name, revision, document, assets, sources, gameScale, catalog, limits and schema. Asset entries include owner-scoped hash, name, size, triangles, pixels, mesh-part count and a public immutable GLB URL. Source URLs identify the platform's prop, game and shell templates.

This reads your editable draft, which can differ from the published version. Batch related changes to keep downloads efficient.

world_upload

Replaces the full draft. It does not publish.

{
  "revision": 1,
  "document": {
    "version": 1,
    "floor": "#dad4c4",
    "walls": "#e8e1cf",
    "entities": [
      {"id":"dice:0","kind":"game","asset":"dice","position":[-8,0,4],"yaw":0,"scale":[1,1,1],"color":"#d7ba7f"},
      {"id":"pillar-west","kind":"prop","asset":"pillar","position":[-14,0,-10],"yaw":0,"scale":[1,3,1],"color":"#ddd6c4"}
    ]
  }
}

The result contains revision and budget, including entities, bytes, manifestBytes, memoryBytes, triangles and pixels. The submitted revision must exactly match the current draft. Validation includes owner asset membership, game identity, transforms, duplicate IDs and budgets.

world_edit_entities

Adds or replaces entities by ID and removes selected IDs in one revision:

{
  "revision": 2,
  "upsert": [
    {"id":"bench-east","kind":"prop","asset":"bench","position":[14,0,8],"yaw":1.5707963267948966,"scale":[1,1,1],"color":"#42756b"}
  ],
  "remove": ["pillar-west"]
}

Both arrays are optional and default to empty. Each permits at most 1,000 entries. Removal happens first; an upsert with the same ID then recreates it. Unmentioned entities and room colors are preserved. The entire resulting world must pass validation. This avoids a huge upload request, but validation and database serialization still process the complete draft; batch related changes together.

asset_upload

{"name":"Ivory planter","glbBase64":"BASE64_OF_A_SELF_CONTAINED_GLB"}

The decoded GLB must be at most 4,000,000 bytes; the encoded JSON is larger. Returns hash, name, size, triangles, pixels and meshes. Reference it as upload:<hash> in a prop entity. The content hash is owner-scoped. Uploads are validated and re-encoded; the returned bytes can differ from the source file.

asset_download

{"hash":"64_lowercase_hexadecimal_characters"}

Returns the library entry and its GLB URL. The hash must belong to the credential's owner. Download the URL as binary GLB data.

REST transfer alternatives

The official bridge uses MCP. Tools that need a binary transfer can also use the following Bearer-authenticated endpoints on https://betworld.gg:

Method	Path	Purpose
GET	/api/worlds/ai/export/world	Full draft and source metadata
GET	/api/worlds/ai/draft/document	Draft, catalog and schema
PUT	/api/worlds/ai/draft/document	Save {revision,document}
POST	/api/worlds/ai/assets/upload	Raw GLB with Content-Type: model/gltf-binary and X-Model-Name

Use Authorization: Bearer …. Native clients can omit Origin; if supplied, it must match the Betworld origin. See the complete HTTP API for owner routes, publishing, credentials, request limits and error responses.

Rate and concurrency limits

World service calls are limited to 120 requests per minute per client IP. Heavy draft writes and reads have bounded admission slots; a busy server returns 503 with Retry-After. Retry transient errors with backoff and jitter. Do not flood retries or parallelize revisions for the same world. Public GLB downloads use a separate higher read limit.

game_skin_contract

Input: exactly {"game":"blackjack"}; game must be a supported asset ID. Read-only. Returns the game's fingerprint, bodyBounds, sourceToWorldScale, ordered controls, optional parts, runtimeMounts, presentation (targets, motion channels, triggers and units), v2 starter template, strict manifest schema, limits and documentation URL. The starter body is an all-zero placeholder, not an uploaded asset. Replace it before saving.

The ordered control catalog describes action/index/seat mappings owned by Betworld. Upload only the slot ID and an asset hash. Doubler/Crash return no physical button slots because their controls are live display regions.

game_skin_save

{
  "revision": 12,
  "skin": {
    "version": 2,
    "id": "ivory-blackjack",
    "game": "blackjack",
    "contract": "REPLACE_WITH_CURRENT_FINGERPRINT",
    "body": "REPLACE_WITH_CONVERTED_BODY_HASH",
    "bindings": [],
    "placements": [],
    "clips": [],
    "motions": []
  },
  "entityIds": ["blackjack:0"]
}

Use real values from game_skin_contract and asset_upload; placeholders above are not valid hashes. Input fields are exactly revision, skin, entityIds. The entity array contains 0–64 unique existing matching game IDs. An empty array saves an unassigned definition. Saving a matching definition ID updates that draft definition; existing entity references remain attached. The response is {revision,budget}. A revision conflict requires downloading and reconciling the latest draft.

Validation rejects wrong-game assignments, missing IDs, unknown/duplicate slots, foreign assets, stale fingerprints, arbitrary action arguments, callbacks and extra fields. Existing references to a replaced definition must still match its game. The saved definition belongs to your connected draft. Publish the finished revision from your world panel.

Read the complete contract for every accepted field, fitting rule and resource limit. world_upload may carry the same definitions, and world_edit_entities preserves the existing skins array while editing references.

background_upload

Pass {name, imageBase64} to upload a PNG, JPEG or WebP panorama. Maximum decoded input: 12,000,000 bytes; width 512–8192; height 256–4096; aspect 2:1 to 8:1; maximum 16,777,216 pixels. The result contains {hash, name, size, width, height, pixels}. Use the hash in document.background with mode: "image" and a numeric yaw, then save through world_upload. Terrain parameters use document.terrain. See terrain and backgrounds.