@vibevibes/mcp

MCP server that connects AI agents to running vibevibes experiences. Agents join rooms, react with tools, and persist memory — as live participants, not request-response endpoints.

Install

# Local dev server (default: localhost:4321)
npx vibevibes-mcp

# Remote shared room
npx vibevibes-mcp https://xyz.trycloudflare.com

# With room token
npx vibevibes-mcp https://xyz.trycloudflare.com?token=abc123

# Via environment variable
VIBEVIBES_SERVER_URL=https://xyz.trycloudflare.com npx vibevibes-mcp

When using @vibevibes/create-experience, the MCP server is auto-registered via .mcp.json — no manual setup needed.

The Agent Loop

Agents are persistent participants in a shared room. The stop hook handles perception — it polls the server for new events and feeds them back as prompts, keeping the agent alive without needing to call watch.

connect → act → (stop hook fires with new events) → act → (stop hook fires) → act → ...

The stop hook automatically delivers events from other participants, available tools per room, and participant lists.

Tools

connect

Join the active room. Returns available tools, current state, participants, and the browser URL.

connect()
→ { tools, sharedState, participants, browserUrl, config }

Call this first. act will auto-connect if you haven't.

act

Execute a tool to mutate shared state.

act(toolName, input?, roomId?)
→ { output, sharedState }

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | toolName | string | — | Tool to call, e.g. "counter.increment" | | input | object | {} | Tool input parameters | | roomId | string | "local" | Target room (for multi-room experiences) |

stream

Send high-frequency state updates (cursors, brushes, sliders) via the stream channel. Bypasses the full tool pipeline.

stream(name, input?, roomId?)

spawn_room

Create a new room running any registered experience.

spawn_room(experienceId?, name?, config?, initialState?, linkBack?, sourceRoomId?)
→ { roomId, url, config }

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | experienceId | string | host | Experience to run in the new room | | name | string | auto | Room name | | config | object or string | — | Config values or preset name (e.g. "boss-fight") | | initialState | object | — | Initial shared state | | linkBack | boolean | true | Store parent roomId in child state | | sourceRoomId | string | "local" | Parent room ID |

list_rooms

List all active rooms with participant counts and configurations.

list_rooms()
→ [{ roomId, participants, events, config, parentRoomId, childRoomIds }]

list_experiences

Show available experiences — the host experience and any registered in vibevibes.registry.json.

list_experiences()
→ [{ id, version, title, description, source, loaded, hasRoomConfig }]

room_config_schema

Get the configuration schema for an experience before spawning a room.

room_config_schema(experienceId?)
→ { hasConfig, schema, defaults, presets, description }

memory

Persistent agent memory. Survives across tool calls within a session.

memory(action: "get")
→ { ...currentMemory }

memory(action: "set", updates: { key: value })
→ { ...updatedMemory }

screenshot

Capture a PNG of the browser canvas.

screenshot(timeout?)
→ PNG image (base64)

Requires the browser viewer to be open. Useful for agents with vision capabilities.

blob_set / blob_get

Store and retrieve binary blobs (pixel buffers, audio data, etc.).

blob_set(key, data)   # data is base64-encoded
blob_get(key) → base64 data

Configuration

The server URL is resolved in this order:

1. CLI argument: npx vibevibes-mcp https://...
2. Environment variable: VIBEVIBES_SERVER_URL
3. Default: http://localhost:4321

Room tokens are extracted from the URL query parameter (?token=abc123) and sent as Authorization: Bearer headers.

Reliability

• Auto-reconnect with exponential backoff on connection failures
• Health checks to detect server restarts and re-join automatically
• Idempotency keys on tool calls to prevent duplicate execution on retry
• Timeout handling with configurable durations per tool

Example: Agent in an Experience

1. connect()
   → See tools: [game.move, game.chat], state: {board: [...], turn: "white"}

2. (stop hook delivers: human moved game.move({from: "e2", to: "e4"}))

3. act(toolName="game.move", input={from: "e7", to: "e5"})
   → Board updated, turn switches

4. (stop hook delivers: human moved again...)

5. act(...)
   → ...forever

Example: Cross-Experience Composition

1. connect()
   → Joined overworld room

2. list_experiences()
   → ["fallout-wasteland", "fallout-combat", "fallout-dialogue"]

3. room_config_schema(experienceId="fallout-combat")
   → { presets: ["radroach-nest", "raider-ambush"], schema: {...} }

4. spawn_room(experienceId="fallout-combat", config="raider-ambush")
   → { roomId: "room-abc", url: "http://localhost:4321/room/room-abc" }

5. act(toolName="combat.attack", input={target: 0}, roomId="room-abc")
   → Combat in child room

License

MIT