Substrata has support for MCP (Model Context Protocol), which allows AI agents such as Claude Code, ChatGPT Codex, and Grok Build to inspect and build in Substrata worlds.
An agent connected over MCP can list worlds and the objects and avatars in them, create objects (including simple primitives like cubes, cylinders and spheres with materials), edit object transforms, delete objects, and render images of the world to see what it has built.
Open up the Substrata native client, version 1.8.0 or newer. Make sure you have created a Substrata account and are logged in in the client.
Open the options dialog (Tools > Options). In the MCP server section near the bottom of the Options dialog, check Enable local MCP server, and click OK.
Go to your personal world in Substrata with the menu command Go > Go to Personal World.While keeping your Substrata native client open, run Claude Code, or ChatGPT Codex, or Grok Build, and tell it something like the following:
Hi, build a Roman temple in Substrata, using the local MCP server at localhost:8095, in the substrata world "YOUR_SUBSTRATA_USERNAME", around coordinates x=100 and y=100
Replace YOUR_SUBSTRATA_USERNAME with your Substrata username - this tells the bot to build in your personal world, instead of the main world.
There are two ways to connect an agent to Substrata:
The server MCP endpoint: Substrata servers with MCP support enabled serve an MCP endpoint at /mcp, e.g. https://substrata.info/mcp. This uses the MCP streamable HTTP transport: the client sends JSON-RPC 2.0 requests over HTTP POST. Requests must be authenticated - see below.
The local client MCP endpoint: The native Substrata client (gui_client) can serve an MCP endpoint on your own machine, at http://localhost:8095/mcp by default. This endpoint provides an additional render_view tool, which renders an image of the currently-connected world from a given camera position, so the agent can actually see what it is building. All other requests are forwarded to the /mcp endpoint of the server the client is connected to, authenticated with your saved login credentials, so no API key setup is needed.
To enable the local endpoint, check Enable local MCP server in the options dialog, as described in the quickstart above. The port can also be changed there (default 8095). For security, the local endpoint only accepts connections from the same machine (loopback/localhost connections).
Requests to the server /mcp endpoint must be authenticated, so that world edits are made as your user, with your permissions.
The recommended method is an API key, passed with an Authorization: Bearer header:
Authorization: Bearer YOUR_API_KEY
To create an API key, log in to the Substrata website, go to your account page, and follow the Manage API keys link. The key is shown once, when it is created - copy it then. You can delete keys from the same page at any time, for example if a key has been leaked, which will immediately stop the key from working.
API keys are the recommended method for connecting third-party MCP clients, since a key can be revoked without changing your password, and your password stays out of client configuration files. (There is also a username/password authentication scheme, Substrata-Login, which is used internally by the Substrata client for the local endpoint.)
The local client endpoint (localhost:8095) does not require an Authorization header, since it only accepts connections from your own machine, and forwards requests using your saved login credentials.
Agents that can run shell commands (such as Claude Code) don't strictly need any MCP configuration: as in the quickstart above, you can just tell the agent the endpoint URL in your prompt, and it will make HTTP requests to the endpoint itself, e.g. with curl.
Registering the endpoint with your MCP client is still worthwhile for regular use: the Substrata tools then appear as first-class tools that the agent discovers automatically, and images from the render_view tool are returned to the agent as actual images, rather than as base64 text it has to decode first. For MCP clients that can't run shell commands (e.g. Claude Desktop), registering the endpoint is the only option.
To connect Claude Code to the local client endpoint (recommended, since it includes the render_view tool):
claude mcp add --transport http substrata http://localhost:8095/mcp
To connect Claude Code directly to a Substrata server, using an API key:
claude mcp add --transport http substrata https://substrata.info/mcp --header "Authorization: Bearer YOUR_API_KEY"
Other MCP clients (e.g. Claude Desktop) can be connected in a similar way: use the streamable HTTP transport with the endpoint URL, plus the Authorization header when connecting directly to a server.
You can test an endpoint with curl:
curl https://substrata.info/mcp -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
list_worlds: List all worlds on the server, with object, avatar and parcel counts. (The main world has the empty-string name.)
get_world_info: Get information about a single world.
list_avatars: List the avatars (users) currently present in a world, with their positions.
list_objects_near: List world objects within a given radius of a point.
get_object: Get the details of a single object by its UID.
create_cube, create_cylinder, create_sphere: Create simple primitive objects, with optional materials (colour, roughness, metallic fraction, opacity, emission, and colour texture). These are useful for blocking out structures like walls, floors and columns.
create_object: Create an object with an arbitrary existing model resource on the server, or special object types like hypercards and text objects.
edit_object: Change the position, scale or rotation of an existing object.
delete_object: Delete an object.
render_view: Render an image of the currently-connected world from a given camera position and orientation, and return it to the agent as an image. Rendering moves the streaming camera and waits for the world to finish loading around it, so this can take a few seconds.
Tools that modify a world act as the user that owns the API key (or the logged-in user, for the local client endpoint), and are subject to the normal Substrata object and parcel permissions: in the main world you can only build in parcels you own or have write permission for, and you can only edit or delete objects you are allowed to modify.
There are also some MCP-specific limits, to stop a misbehaving agent from filling up a world: a maximum number of MCP-created objects per parcel, and per (non-main) world. Requests are rate-limited per user.
If you are running your own Substrata server, the MCP endpoint is enabled by default, and can be disabled with the enable_mcp_server setting in the server config file.
< Home