forma-engine/docs/MCP.md

MCP setup

Forma uses the MCP TypeScript SDK with Streamable HTTP and a stdio adapter. Both access the same project as the local browser editor.

Start the engine

npm ci
npm run build
npm start -- --project ./projects/MyProject

Open http://127.0.0.1:4318/. The server creates a private .mcp-token file inside the project folder. The token is a credential and is excluded from Git.

The HTTP endpoint is http://127.0.0.1:4318/mcp. Clients send Authorization: Bearer <token>. This stateless endpoint accepts MCP POST requests; GET and DELETE return 405.

Local stdio client

Configure a compatible client using absolute paths:

{
  "mcpServers": {
    "forma": {
      "command": "node",
      "args": [
        "/absolute/path/forma-engine/server/stdio.mjs",
        "--project",
        "/absolute/path/forma-engine/projects/MyProject"
      ]
    }
  }
}

The adapter connects to an already running local HTTP service. It resolves the TypeScript loader relative to the engine installation, so the client's working directory can differ. Standard output contains only protocol messages.

For a non-default server port, add --url and http://127.0.0.1:4320/mcp to the adapter arguments. Each adapter must use the folder belonging to that server's project.

Agent workflow

1. Call project_read and read forma://reference/commands and forma://reference/scripts.
2. Apply related edits together with commands_apply, using the current expectedRevision.
3. On a revision conflict, reread the project. When retrying the same request, retain its requestId.
4. Inspect the scene and diagnostics. Use runtime_play, input, snapshot and capture tools to check the running project.
5. Save the project and request a web or application build.

runtime_capture returns a real PNG from the connected viewport. Runtime tools require an open local editor tab. EDITOR_DISCONNECTED means no tab is connected; EDITOR_TIMEOUT means the editor did not answer within 15 seconds. Keep one editor tab open for automation.

model_generate and mesh_create support procedural geometry without Blender. Imported files may be supplied as base64 or by a path within the project folder. Game logic is authored in project scripts; the engine does not ship a complete game.

The server exposes its current schemas through MCP discovery. Static reference files in docs/ document commands and script APIs.

Remote clients

A cloud client cannot directly reach 127.0.0.1 on your computer. A compatible secure connection or authenticated HTTPS gateway is needed. Forma does not include OAuth, a hosted MCP service or an automatic tunnel installer. Account-specific connector setup is separate from installing this engine.

The local editor service is designed for loopback use. Remote access needs a deployment designed for that environment; changing the bind address alone does not provide one.