Configuration¶

Everything is optional. Environment variables use the prefix SNAIL_MCP_BLENDER_, with __ between a section and a field.

Every range lives as an attribute on the setting it constrains, and the server checks them all while the host starts: a port outside 1 to 65535, a timeout of zero or less, negative minutes, link minutes outside 1 to 1440. The process then exits with OptionsValidationException naming each setting it refused and the range it allows; a server over HTTP without a client token exits the same way, naming HTTP__TOKEN and HTTP__TOKEN_FILE. A value that is not a number, or a PYTHON or TRANSPORT that is none of its names, stops the process with InvalidOperationException instead. Nothing is repaired in silence, so a typo in the environment is visible immediately instead of turning into a link that never connects.

Token¶

The add-on demands a token on every request. Left empty in its preferences, it generates one on first start into <data directory>/state/token, readable by the user only, and the server reads that file whenever it connects, so a fresh install needs nothing typed. Set the same value on both sides by hand when the server and Blender use different data directories. For a Blender on another machine, copy the token it generated into a file readable by you alone and point SNAIL_MCP_BLENDER_BRIDGE__TOKEN_FILE at it, so the MCP entry holds a path and no secret; Blender on another machine shows the commands. A Blender without an interface takes its token from blender -b -c snail_bridge --token-file <file> instead, and --host sets the address it listens on, the container network in Docker; point SNAIL_MCP_BLENDER_BRIDGE__TOKEN_FILE at the same file.

Clients and their keys¶

A server reached over HTTP admits clients by key, one key each:

$ s3l-mcp-blender clients add lighting --scope read,write,farm
lighting — read, write, farm
l7m82DheQD9RO3z3RWjSgr0Gv87LgkjQfGvRwEDPhTk
This is the only time the key is shown; give it to the client and keep no copy here.

The client sends it as Authorization: Bearer <key>. clients list names the clients and what each may do, and clients revoke <name> stops admitting one — at its next request, without restarting the server, and its browser session with it. Only the digest of a key is kept, under <data directory>/state/clients.json, so a copy of that file opens nothing and a key that is lost is reminted rather than looked up.

The name on the key is the agent name the client's commands are signed with, which the add-on's leases and journal record; the client cannot choose it (see Agents).

A key minted without --scope gets read, write, delete and farm: Python is asked for by name.

run_tools and run_program need no scope of their own: each command they carry is asked about by its own scope before any of them is sent, so a key with read, write and farm runs a program that builds a scene and is refused one that deletes from it. blender_batch needs farm, because it starts a second Blender, and then the same for every step. blender_upload is write work, and delete only with overwrite, which replaces a file that is there — the same over /raw with a key; a signed link was granted by the tool that issued it and needs no scope.

SNAIL_MCP_BLENDER_HTTP__TOKEN still works and opens everything, so a server set up before keys existed keeps running and its clients move over one at a time. It is also the only key whose holder may still name itself with the header X-Snail-Agent.

State the add-on keeps¶

The add-on writes what must outlive a Blender session under <data directory>/state: journal.jsonl (every mutating command with its agent), leases.json (objects agents hold) and jobs.json (the render queues to pick up after a restart). Worker Blenders started for batches and render jobs inherit the data directory, so their commands land in the same journal and respect the same leases. The add-on reads SNAIL_MCP_BLENDER_DATA_DIRECTORY from Blender's own environment; when Blender is started from a launcher without it, the default ~/.s3l-mcp-blender applies, which is also the server's default — or ~/.snail-mcp-blender while only a folder of that name, from before the rename, is there. Next to state/ it keeps jobs/, batches/, snapshots/ and files/, all on the machine Blender runs on; the working order maps them.

Settings file¶

The same keys as a JSON file, under a Snail section. The chain is Snail.Sdk's, the same for every Snail server. A file named in SNAIL_MCP_BLENDER_CONFIG is the only one read, and when it does not exist no file is. Without that variable only the first file that exists is read: .s3l-mcp-blender.json and s3l-mcp-blender.json in the working directory, ~/.config/s3l-mcp-blender/config.json, ~/.s3l-mcp-blender.json. The names from before the rename are not read.

{
  "Snail": {
    "Bridge": { "Port": 9876, "RequestTimeoutSeconds": 45, "Token": "the add-on's token" },
    "IdleTimeoutMinutes": 0
  }
}

Environment variables win over the file, setting by setting.

A setting of this machine — a token above all, Bridge.Token or Http.Token — belongs in ~/.config/s3l-mcp-blender/config.json, readable by you alone (chmod 600), never in a launchd job or in a client's registration: those travel wherever the file is copied, and the settings file serves every client and a server over HTTP alike.

Limits¶