MCP Server Usage & Architecture Guide

Connecting Model Context Protocol (MCP) clients to the inworld-hub server, tool reference, and grid automation scenarios.

New here? Start with the overview: How we build a living grid presence in Luau — the system and workflow at a glance. This page is the MCP tool reference.

1. Introduction & Architecture

The Model Context Protocol (MCP) server is folded directly into the main Luau server (server/mcp.luau) on inworld-hub. Because the hub process maintains live WebSocket connections to every active bot (running libremetaverse-lua), the MCP endpoint reaches registered bots in-process without external bridges or extra network hops.

   ┌──────────────────────────────────────────────────────────────┐
   │  MCP Client (Agent / Operator Tooling)                        │
   └──────────────────────────────┬───────────────────────────────┘
                                  │ HTTP POST /mcp (Streamable HTTP)
   ┌──────────────────────────────▼───────────────────────────────┐
   │  inworld-hub (server/mcp.luau + hub.luau on ukulele)          │
   │  JSON-RPC 2.0 (Spec version 2025-06-18)                      │
   └──────────────────────────────┬───────────────────────────────┘
                                  │ WebSocket Relay (bot.eval / bot.run)
   ┌──────────────────────────────▼───────────────────────────────┐
   │  libremetaverse-lua Bot Processes (inworldhelp, etc.)        │
   │  Embedded Luau VM + client.* Grid & Web Bindings              │
   └──────────────────────────────────────────────────────────────┘

AI assistants and automated clients inspect grid state, trigger movement, manage Marketplace listings, and run standing services through simple MCP tool invocations.

2. Protocol & Framing

3. Client Configuration

Configure the server in your MCP client configuration:

{
  "mcpServers": {
    "inworld-hub": {
      "type": "http",
      "url": "http://127.0.0.1:8300/mcp"
    }
  }
}

4. Management Tools

Tool NameArgumentsDescription & Behavior
bots_list{}Returns a newline-separated list of IDs of bots registered with the hub.
bot_eval{id, source}Evaluates arbitrary Luau source inside the target bot's VM. Captures streamed print() lines ahead of the JSON result. Coroutine-backed (top-level await supported).
bot_run{id, script, args?}Runs a saved library script (from bots/scripts/<category>/<name>.luau) with an args table and returns JSON result.
ans_salt{label, salt, merchant?}Registers a merchant store's 40-character hex ANS verification salt in the server database.
bot_services{id}Lists a bot's loaded Luau services, runtime states (running, stopped, error), and startup status.
bot_service{id, action, name, namespace?, tenant?}Controls a service: start | stop | restart | enable | disable | enable-entitled.

5. Typed Grid-Op & Bot Control Tools

Typed convenience wrappers over bot_eval for high-frequency grid actions:

Tool NameArgumentsDescription
bot_chat{id, message, channel?, type?}Sends region chat. channel defaults to 0; type is "normal", "whisper", or "shout".
bot_im{id, target, message}Sends instant message to an avatar or group UUID.
bot_rez{id, shape?, position?, scale?}Rezes a basic prim shape (box, sphere, cylinder, prism) in-world. position defaults to 1m in front of bot.
bot_teleport{id, region, x?, y?, z?}Teleports bot to target region name and (x, y, z) coordinates.
bot_region_state{id}Inspects bot self identity/position, nearby avatar list, and cached prim count.
bot_read_inventory{id, folder_uuid?}Lists contents of inventory folder (defaults to root folder if omitted).
bot_sit{id, target}Commands bot to sit on target object UUID (coroutine await with 10s timeout).
bot_stand{id}Commands bot to stand up.
bot_pay{id, target, amount, is_object?, description?}Pays Linden Dollars (L$) from bot account to an avatar or object.
bot_friends{id}Lists bot's friends roster and online statuses.
bot_subscribe{id, events?, sub_id?}Subscribe to push event notifications for a bot or all bots (*). Events: im, chat, alert, nearby, payment, output, or *.
bot_unsubscribe{id, sub_id?}Unsubscribe from event notifications for a bot or session ID.
bot_events{sub_id?, clear?}Fetch queued event notifications (pushed IMs, chat, alerts, radar) for subscriber.
bot_subscriptions{sub_id?}List active event subscriptions and pending message counts.

6. Coroutine Execution & Scripts

Every bot_eval and bot_run tool call executes inside a resumable Luau coroutine on the bot's single worker thread. When a script calls an async completion method without a callback (such as client.self.sit(uuid) or client.marketplace.listings()), the call yields the coroutine. Once the correlated reply or alert arrives from the grid, the VM resumes the coroutine and returns the values inline without blocking other queued tasks.

Result Encoding

To safely return complex Luau data structures (tables, arrays, nested maps) over JSON-RPC, bot_run and typed grid-op tools wrap code with an in-VM JSON encoder (RESULT_ENCODER) so the evaluated return value arrives as clean JSON.

7. Practical Integration Scenarios

Scenario A: Evaluating Custom Luau Source

# HTTP Request to evaluate avatar position and send chat
curl -s -X POST http://127.0.0.1:8300/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 101,
    "method": "tools/call",
    "params": {
      "name": "bot_eval",
      "arguments": {
        "id": "inworldhelp",
        "source": "local p = client.self.info().position\nprint(\"Current pos: \" .. p.x .. \", \" .. p.y)\nclient.chat(\"Standing at \" .. math.floor(p.x) .. \", \" .. math.floor(p.y), 0)"
      }
    }
  }'

Scenario B: Running Reusable Library Script (`bot_run`)

# Run marketplace/update script with arguments
curl -s -X POST http://127.0.0.1:8300/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 102,
    "method": "tools/call",
    "params": {
      "name": "bot_run",
      "arguments": {
        "id": "inworldhelp",
        "script": "marketplace/update",
        "args": { "listing_id": 28516944, "is_listed": true }
      }
    }
  }'

Scenario C: Regional State & Avatar Radar

# Inspect region state via typed tool
curl -s -X POST http://127.0.0.1:8300/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 103,
    "method": "tools/call",
    "params": {
      "name": "bot_region_state",
      "arguments": { "id": "inworldhelp" }
    }
  }'

MCP Implementation: server/mcp.luau & server/hub.luau. Server endpoints: http://127.0.0.1:8300/mcp.