WorldBridge MCP

A standalone, portable MCP server that lets any AI assistant act as the Gaia of an OpenSimulator region -- build, sculpt terrain, script, move avatars, and read the world -- through the WorldBridge (worldbridge/) region module's control channel, and see the world through its own viewer.

Nothing here is tied to any one host or product: it is pure Python stdlib (no pip install), and every connection detail is an environment variable. Load the WorldBridge module into your OpenSim, point this MCP at your channel, and you have the same powers on your own world. A full setup, from building the server to connecting an AI, is in ../handbook/quickstart.md.

Configure

viewer_look asks the bridge for a snapshot by bare file name; the bridge writes it inside its own snapshot folder (PARACOSM_SNAPSHOT_DIR, see tools/PORTABILITY.md) and answers with the full path, which the MCP reads and deletes.

This server does not read the Paracosm .env; give it its variables in the MCP client's configuration. It reads the WorldBridge token once, when it starts (start OpenSim once first, so the token file exists); the viewer bridge's token is read on every call, so a relaunched viewer is picked up.

Add to an MCP client

{
  "mcpServers": {
    "worldbridge": {
      "command": "python",
      "args": ["/path/to/paracosm/mcp/worldbridge_mcp.py"],
      "env": {
        "WORLDBRIDGE_URL": "http://127.0.0.1:9002",
        "WORLDBRIDGE_TOKEN_FILE": "/path/to/opensim/bin/WorldBridge.token"
      }
    }
  }
}

Speaks MCP over stdio (newline-delimited JSON-RPC 2.0). Quick smoke test without a client (the second call needs the server running):

printf '%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"world_state","arguments":{}}}' \
 | WORLDBRIDGE_TOKEN_FILE=/path/to/opensim/bin/WorldBridge.token python worldbridge_mcp.py

Tools (version 0.2): 26

The viewer_* tools need the AI's own viewer running with its bridge: build and start it as described in ../handbook/viewer.md.

Security

The WorldBridge module binds 127.0.0.1 only and requires the bearer token; this MCP runs on the same host and talks to that loopback channel, so there is no public attack surface by default.

RBAC (built in): the module supports role-scoped tokens -- observer (read-only: state, list, heightmap, avatars, chat, inspect, worn, contents, roam_notecard), builder (+ spawn, recolor, rez_item, put_notecard), gaia (everything else) -- configured as TokenObserver/TokenBuilder/TokenGaia (16 characters or more) in the module's [WorldBridge] ini section (in Paracosm, from the .env keys WORLDBRIDGE_OBSERVER_TOKEN/_BUILDER_TOKEN/_GAIA_TOKEN through tools/make_config.py). The generated token file holds a gaia token. Whichever token you give this MCP determines what it can do: a builder token gets a 403 forbidden (naming the role needed) if it calls world_terrain. Give an assistant the lowest role it needs. A leaked low token cannot wreck the world.

world_call can reach every command the token's role allows, including console when the module's AllowConsole is true (it is false by default).

If you ever expose the channel beyond localhost, do NOT do so without also adding TLS + rate-limiting on top of the token/RBAC (see PLAN.md "SECURITY OF THE CONTROL CHANNEL").

Not yet here

Driving a LibreMetaverse avatar (walking the world as a player) is a separate process today (see bot/); folding it into this MCP is a planned addition. The viewer_* tools drive a real viewer instead.