# Connect MCP

## Endpoint

```text
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:

```json
{
  "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:

```bash
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](/downloads/betworld_blender.py) 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](/world-api/).