MCP Server

What It Is

An MCP server is a program an AI client starts and talks to over a standard protocol, so the model can call its tools and read its resources. eustress-mcp is Eustress's server: one native binary that the client launches as a child process and speaks to over standard input and output, one JSON-RPC 2.0 message per line. It answers MCP protocol versions 2025-06-18, 2025-03-26 and 2024-11-05, echoing whichever the client asks for.

It exposes about 120 tools and six kinds of resources. Most tools are the same handlers the in-engine Workshop assistant uses, from the shared eustress-tools crate; the others, most of them live tools, exist only in the server. Each request runs on its own task, so a long call such as await_simulation never blocks the others, and a client can cancel it. In Studio, Help > Setup MCP opens this page.

Disk and Live

Every tool reaches a Space in one of two ways. Disk tools read and write the Universe folder, and a running engine picks the change up through its file watcher, so they work with Studio closed. Live tools connect to the engine's bridge, a JSON-RPC endpoint on 127.0.0.1, and act on the world the engine has loaded right now.

The entity tools do both: they try the bridge first and fall back to the files when no engine answers. The simulation tools are a third case, covered in Simulation and Physics.

Get the Binary

Build the server from a source checkout, in the repository's eustress folder:

cargo build --release -p eustress-mcp-server

# Windows:        target/release/eustress-mcp.exe
# macOS, Linux:   target/release/eustress-mcp

The Windows installer copies eustress-mcp.exe into the install folder only when the build that precedes it has produced the file. The release pipeline builds only the eustress-engine package, so installers it produces do not include the server: build it as above and point your client at the file.

Build eustress-mcp-server, not eustress-mcp

The binary is named eustress-mcp, but its package is eustress-mcp-server. The workspace also holds a package called eustress-mcp: an older library that builds no program, so cargo build -p eustress-mcp finishes without producing a server.

Register It with Your AI Client

The server needs no arguments. Name the Universe it should work in with an environment variable and register it under any name. For Claude Code, add it to .mcp.json in your project:

{
  "mcpServers": {
    "eustress": {
      "type": "stdio",
      "command": "C:\\Eustress\\eustress\\target\\release\\eustress-mcp.exe",
      "args": [],
      "env": {
        "EUSTRESS_UNIVERSE": "C:\\Users\\you\\Documents\\Eustress\\Universe1"
      }
    }
  }
}

Other MCP clients take an equivalent entry, with the same command, arguments and environment, in their own configuration file. Claude Code shows the tools with its server prefix, for example mcp__eustress__inspect_scene. Everything the server reads at startup:

Which Universe and Space

At startup the server picks its Universe from the first of these that gives one:

1. The --universe argument.
2. The EUSTRESS_UNIVERSE variable.
3. The nearest folder above the working directory that contains a Spaces folder.

If none does, the first resource request adopts the first Universe found in the search folders. Resources always come from this Universe, and the set_active_universe tool switches it mid-session.

Tools follow Studio's last Space

When Studio has run on this computer, every tool call works in the Space Studio last had open, read from last_space_path in ~/.eustress_engine/settings.json, and in that Space's Universe, even when EUSTRESS_UNIVERSE names another. Only without that setting does a tool fall back to the configured Universe and its first Space. Open the Space you want in Studio before you point an agent at it.

A live tool connects to the port in .eustress/engine.port of the Universe it works in, and falls back to the copy of that file in the folder above. Without Studio's setting, the server first searches the search folders for a Universe whose port file names a port that accepts a connection within 250 ms, and remembers the answer for 3 seconds, so closing one engine and opening another needs no restart.

Check the Connection

On start the server logs its version, the Universe it resolved, its search folders and its tool count to stderr, which your client may show in its MCP log. Then ask the assistant to call list_spaces: it names the Spaces of the Universe it is working in. With no Universe resolved, resources/list offers a single resource, eustress://help/setup, that explains how to set one.

To test the live path, open a Space in Studio and call inspect_scene. It returns the loaded entities and the current frame rate. With no engine running, a live tool answers that the engine is not running and suggests opening Studio or starting eustress-headless.

What a Client May Call

Every tool belongs to one capability class, set in a single table in the eustress-tools crate, and the dispatcher checks the class before the tool runs. An MCP client gets the standard grant, Read and Write. Tools in the other classes still appear in tools/list, and a call returns a permission error that names the missing capability.

Twelve live tools are refused today

A tool missing from the capability table is refused even with full permissions. Twelve of the server's own live tools are missing from it: equip_tool, select_entity, invoke_action, capture_viewport, the four ai_camera_ tools, export_instances_toml, data_bind, data_bindings and data_unbind. They are listed, and every call returns a permission error. The bridge methods behind them work from the eustress CLI.

The Universe Sandbox

• File tools: read_file, list_directory and write_file take paths relative to the Universe root. A path containing .. is refused, and so is any path that resolves outside the Universe.
• Entity files: write_file will not overwrite an _instance.toml; entities change through create_entity and update_entity.
• Size caps: read_file returns the first 50,000 bytes of a file, resource reads stop at 256 KB, and a tool's structured result is cut at 120 KB with an explicit truncation note.
• The protocol stream carries only protocol messages. The server's own log goes to stderr.

Review and Audit

Each tool in tools/list carries MCP annotations taken from its own code: readOnlyHint on tools that only observe, destructiveHint on tools that ask for approval in the Workshop, and openWorldHint on http_request. Clients use them to decide which calls to confirm with you.

stage_file_change writes nothing. It returns the proposed create, modify or delete, with the file's current text for a modify, so the client can show it to you before anything is written.

Two logs show what happened in a Space. query_audit_log reads the engine's record of its own Claude calls, one .log.toml file per call under SoulService/Logs. oplog_tail reads the engine's op-log of entity creates and deletes, in order.

The bridge trusts local programs

The engine bridge listens only on 127.0.0.1 but checks no identity: any program on your computer that reads engine.port can connect and call any bridge method, including entity.delete and engine.shutdown. Only its tools.call method is limited, to the same Read and Write set as the MCP server.

Universes and Spaces

Files and Scripts

Scripting itself is covered in Scripting.

Entities

Tools marked live first call the engine's bridge, where new parts go into the world database, and fall back to writing _instance.toml folders when no engine answers. An engine that is up but rejects the call reports the error instead of a silent disk write.

Git, Memory and Logs

How a Universe's history is kept is covered in Universes.

The Engine Bridge

Every running engine, the Studio window and eustress-headless alike, hosts the Engine Bridge: a JSON-RPC 2.0 endpoint on 127.0.0.1 at a port the operating system picks. The engine writes that port to .eustress/engine.port in the Universe it has open, and a copy to the same path in the folder above, the workspace root. Requests are handled on the engine's main thread, up to 64 per frame, so a handler sees exactly the world on screen.

The server connects with a 2 second limit and gives most calls 2 seconds to answer; sim_step waits longer in proportion to the ticks it asked for. When several engines share one Universe, engine.port names only one of them; CLI & Headless covers the instance registry that lists them all.

Scene and Editor

Large scenes: overview, partition, then page

Call scene_overview to see where things are, partition_scene to cut the world into one unit per agent, then page each unit's cells with inspect_scene and its cell argument, instead of paging one flat list of every entity.

AI Camera and Capture

The AI camera is a second, off-screen camera inside the engine, separate from your view, that renders only when asked. All five tools here are refused over MCP today, because they are missing from the capability table.

Simulation and Physics

The simulation tools reach an engine through files rather than the bridge, because they also run inside the engine, where a call to its own bridge would wait on itself. They queue a command in a file the engine reads every frame and read the runtime snapshot it rewrites 4 times a second, so results need an engine with the Universe open. With several engines on one Universe, pass pid to choose one. The waiting tools stop early when the client cancels. The clock and watchpoints themselves are covered in Simulation.

CAD

The CAD tools author and inspect parametric CadPart feature trees on disk, with no engine needed. Each authoring call reports the part's state back, so an agent sees a defect as soon as it makes one. The parts themselves are covered in CAD.

Website and Moderation

The Website tools edit a Space's Website service as TOML, so they work without an engine; see Website Service. The moderation tools serve Eustress's Gallery moderators and act on eustress.dev, so they need the Network capability that EUSTRESS_MODERATOR_TOKEN grants.

Generation and Network

The last four hand their request to an engine-side lookup. Over MCP there is no engine behind the call, so they answer with what was asked rather than results.

Resource URIs

A resource is a document the client can read and pin. The server publishes six URI templates; {+path} keeps its slashes, so nested folders round-trip.

resources/list returns the Spaces, their scripts (up to 500), the 20 newest conversations and the briefs, 100 per page with a cursor, up to 2,000 entries.

Subscriptions

Subscribe to a resource and the server sends notifications/resources/updated when its file changes. A file watcher starts with the first subscription and stops with the last. It watches the Universe's Spaces folder and its saved sessions, lets a burst of writes settle for 120 ms, and reacts to .rune, .luau, .soul, .md, .toml and .json files outside .git, target and node_modules.

Switching Universe with set_active_universe moves the watcher and sends notifications/resources/list_changed, so the client drops a list that belongs to the Universe it left.

Editor Control over MCP

The twelve refused live tools will become callable once they have entries in the capability table: the AI camera, viewport capture, tool and selection control, editor actions, Dataset bindings and database export. The engine side of each already answers on the bridge, so an agent will see and steer Studio through MCP the way the eustress CLI can today.

Packaging and Pass-Through Tools

The installer already has a place for eustress-mcp; a release build step for its package will put the server beside Eustress Engine on every install. The disk raycast tool will route to the bridge's live physics, and the request-only tools will return results once they have a store or an engine behind them out of process.