MCP Server¶

The editor can run a Model Context Protocol (MCP) server, so AI agents outside it — Claude Code, Codex, Gemini CLI and other MCP clients — can work on the open project with the same tools as the built-in AI Chat: inspect scenes and entities, add components, write scripts, fork shaders, run a scene and read the output log.

The agent brings its own model and account. The editor only runs the tools, so no API key is needed here and the AI Chat can stay closed. The server works on whichever project the editor has open, so opening another project changes what agents see, and an agent can open or create one itself.

Turning it on¶

1. Open Edit → Editor Settings → AI and expand MCP Server.
2. Tick Enable Server and press OK.

The Output panel reports MCP server listening on http://127.0.0.1:3674/mcp, and the server starts with the editor from then on.

The token is created and kept the first time the section opens, and replacing it takes effect at once, so a command copied from here keeps working whether the dialog closes with OK or Cancel. The other fields apply on OK.

Connecting Claude Code¶

Copy the Claude Code row and run it in a terminal:

claude mcp add --transport http doriax http://127.0.0.1:3674/mcp \
  --header "Authorization: Bearer <token>"

The command adds the server for the folder you run it in, so run it in the project folder, where Claude Code can also read the project's files. Add --scope user after --transport http to have it in every folder. In a Claude Code session, /mcp then lists doriax as connected, with its tools.

Connecting Codex¶

Copy the Codex row and run it in a terminal:

codex mcp add doriax --url http://127.0.0.1:3674/mcp --bearer-token-env-var DORIAX_MCP_TOKEN

Codex keeps the token out of its configuration: it reads it from the DORIAX_MCP_TOKEN environment variable each time it connects. Set that variable to the token (Copy on the Token row) where Codex runs, for example in your shell profile:

export DORIAX_MCP_TOKEN=<token>

On Windows, setx DORIAX_MCP_TOKEN <token> sets it for terminals opened afterwards.

Connecting Gemini CLI¶

Copy the Gemini CLI row and run it in a terminal:

gemini mcp add -s user --transport http --header "Authorization: Bearer <token>" \
  doriax http://127.0.0.1:3674/mcp

-s user saves the server in your user settings. Without it, Gemini CLI writes it to .gemini/settings.json in the current folder, token included, where it could end up in version control.

Other clients¶

Any other client that speaks MCP over Streamable HTTP and can send a custom header works: give it the URL and the header Authorization: Bearer <token>. A client that can only start local (stdio) servers needs a stdio-to-HTTP bridge in between.

{
  "mcpServers": {
    "doriax": {
      "type": "http",
      "url": "http://127.0.0.1:3674/mcp",
      "headers": { "Authorization": "Bearer ${DORIAX_MCP_TOKEN}" }
    }
  }
}

What agents can do¶

The server offers every tool the AI Chat uses, with the same checks and the same results, plus open_project and create_project, which only MCP clients get: the chat runs inside the editor, and switching projects would end its own turn. Each tool is marked read-only or not (readOnlyHint), which clients can use when they ask you to confirm a call.

When a client connects, the server also sends the engine rules the AI Chat's model gets: how Lua and C++ scripts are written, to confirm an API in the engine source before using it, how physics bodies get their shapes, how to verify a script by running the scene and reading the log. An agent that reads them follows the same conventions as the AI Chat.

How calls run¶

• Each call runs on the editor's main thread between frames, one at a time, exactly as if the AI Chat made it. A long action such as an export holds the editor until it ends.
• Scene edits go through the editor's undo history, so Edit → Undo reverts what an agent did.
• Each change an agent makes is logged in the Output panel as MCP: <what it did>, and a failed call as a warning or an error.
• While a project is loading, calls wait. A call still waiting after two minutes fails, and the agent is told to try again.
• A call the client gives up on before it starts, for example when you cancel it, is dropped. One already running is asked to stop early where the action supports it, as an export or an asset download does.

Saving an agent's work¶

Agents save with save_scene, save_all_scenes and save_project, like the AI Chat. Two saves would need a dialog that only you can answer, so the tools take a path instead:

• A scene that was never saved. save_scene with a project-relative path, such as scenes/Level1.scene, saves it there. Without one, and with save_all_scenes, which takes no paths, the editor opens the Save Scene dialog for you.
• A temporary project. save_project with an absolute path moves the project out of the system temp folder, as Save Project does, into a directory that is empty or does not exist yet. An optional name renames it too. A project that is not temporary is saved where it is, without path.

Tools that would stop to ask you about unsaved work refuse instead, and tell the agent what to save first. create_scene, for example, closes the selected scene, so it refuses while that scene or one of its child scenes has unsaved changes.

Opening and creating projects¶

Two tools replace the project the editor has open, and only MCP clients have them:

• open_project opens an existing project directory, the one holding project.yaml, as File → Open Project does.
• create_project creates a project in an empty or new directory and opens it. It is named after the directory unless the agent passes name, and starts with an unsaved 3D scene, New Scene, which save_scene with a path keeps.

Both take an absolute path. The switch happens after the call returns, and the agent's next calls wait until the new project has loaded.

The editor does not drop work to switch, so both refuse where its menus would ask you first:

The temporary project the editor opens at startup holds no work until you or an agent change it, so an agent can switch away from it at once.

Security¶

The server is meant for agents running on your own computer:

• It listens on 127.0.0.1 only.
• Every request must carry the token as Authorization: Bearer <token>. A missing or wrong token is answered with HTTP 401.
• Requests from web pages are refused with HTTP 403: the server checks the Origin header, so a site cannot reach it through your browser, not even by pointing its own domain at 127.0.0.1.
• The token is stored obfuscated in ai_keys.dat, beside the editor's settings.yaml, and never in the project.

Treat the token like access to the editor itself. With Allow Changes on, an agent can write scripts and build settings, and those run on the next Play or export. A replaced token applies from the next request, so every connected client needs the new command.

Troubleshooting¶

Protocol details¶

For client authors:

• Transport: Streamable HTTP on one endpoint, POST /mcp. Every response is a single JSON object, never an SSE stream. GET and DELETE return 405.
• Versions: 2026-07-28 (stateless: server/discover, _meta on every request, and the mirrored MCP-Protocol-Version, Mcp-Method and Mcp-Name headers checked), plus the initialize-based 2025-11-25, 2025-06-18 and 2025-03-26. No sessions are created.
• Capabilities: tools only, with no resources, prompts or change notifications. The tool list only changes with Allow Changes, but that can happen at any time, so under 2026-07-28 the server/discover and tools/list results are marked never to be cached (ttlMs: 0, cacheScope: "private").
• Results: text content holding the action's message followed by its data as JSON. A failed action is a result with isError: true, so the model can correct itself; an unknown tool or a malformed request is a JSON-RPC error.

Where the values are stored¶

Both files are in the editor's settings folder, which the FAQ lists per platform.

See also¶

• Editor Settings — the MCP Server section, beside the AI Chat's keys
• Command-Line Tools — exports, shader builds and benchmarks without the editor window
• Model Context Protocol — the specification