Skip to main content

Connect MCP

Read this page as Markdown · All docs for AI agents

Endpoint​

https://betworld.gg/api/worlds/ai/mcp

The server uses Streamable HTTP, with stateless requests. Use a client that supports remote HTTP MCP and custom Bearer headers. A client that only supports local stdio needs a compatible HTTP bridge. A client that requires OAuth-only remote connections cannot use this credential directly; Betworld does not currently provide MCP OAuth discovery or an OAuth consent flow.

Configuration example​

This is a common JSON configuration shape; your client's setting names may differ:

{
  "mcpServers": {
    "betworld": {
      "url": "https://betworld.gg/api/worlds/ai/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_WORLD_CREDENTIAL"
      }
    }
  }
}

Generate the real configuration from Create world → Create MCP credential. Store the credential in client secret settings where available. Never commit it, include it in screenshots, embed it in models or put it in a public URL.

Scope and lifetime​

Each credential is bound to one owner and one world. It permits downloading that draft, saving changes and uploading static props to the owner's library. asset_download only resolves assets in that owner's library.

It cannot publish, access wallets, place bets, modify another owner's world or execute server code. It has no automatic expiry: it remains valid until you revoke or replace it. Generating a replacement or clicking Revoke access invalidates the old token. Blender stores the token in a transient WindowManager property with SKIP_SAVE; the world file does not contain it.

Check the connection​

Use your client's standard initialization and tool discovery flow. tools/list should expose world_download, world_upload, world_edit_entities, asset_upload and asset_download.

For an HTTP diagnostic, set BETWORLD_TOKEN privately in your shell and initialize:

curl --fail-with-body https://betworld.gg/api/worlds/ai/mcp \
  -H "Authorization: Bearer $BETWORLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"world-builder","version":"1.0"}}}'

Let the client honor the protocol version returned by initialization. The official Blender bridge also supports the installed server's newer protocol framing. Do not assume an arbitrary protocol version is accepted.

A persistent GET event stream returns 405 because this server is stateless. This does not mean that POST tool calls are unavailable. The bridge can read completed JSON or SSE responses.

Betworld MCP and Blender MCP​

These are two separate connections:

  1. Betworld MCP, hosted remotely, reads and validates your world and assets.
  2. Blender MCP, on your computer or trusted workstation, lets the AI operate Blender.

Use the official Betworld Blender bridge to transfer scenes. Install it from disk in Blender's add-on preferences, then open the Betworld sidebar. A local Blender MCP can invoke its operators and manipulate the imported scene. The remote Betworld service does not execute Python sent by a model.

Only expose a local Blender MCP to a trusted client. It can run code on the machine where Blender runs; keep it bound to localhost or behind authenticated private access. This is separate from the restrictions on uploaded world data.

The credential-creation response returns expiresIn: null. Your token remains valid until you revoke it or generate a replacement. Paste it again when reopening Blender if needed; the bridge keeps it outside your saved scene.

For REST requests and credential management, see the World HTTP API.