Setup

Before you start#

You need two things:

• The Vastopia editor, installed as described in Install the editor. The MCP server ships inside it at tools/vastopia-mcp/ next to the editor executable — vastopia-mcp-win.exe on Windows, vastopia-mcp-macos on macOS. A Linux binary (vastopia-mcp-linux) is not bundled by default.
• An MCP-capable AI app. The editor knows how to configure Claude Code, Claude Desktop and Cursor directly, and can show you the config to paste into anything else.

Sign in to the editor if you want the assistant to be able to publish. Without a login the assistant still authors content; it just cannot push builds (author-only mode).

Enable AI from the editor#

This is the recommended path. The editor already knows your project path, your login and the API it talks to, so it writes a complete client config with no typing.

1. Open your game in the editor.
2. Click the AI Off chip at the right end of the top bar (its tooltip reads "AI assistant — click to configure"). The AI Assistant window opens.
3. The window's header shows the bound state — "AI: Off" and "Enable AI to let your assistant build this game." while nothing is enabled. Below it, the AI apps card lists the apps the editor can configure. Apps it could not detect on this machine carry a not detected badge; project-scoped entries (Claude Code and Cursor) are always offered, because enabling them only writes a file inside your project.
4. Decide whether to leave Allow publishing (writes your API key to the config) checked. Checked, the assistant can push and deploy builds on your behalf. Unchecked, your credential never reaches the config file and publishing tools fail with a clear message.
5. Click Enable beside the app you use. The result line reports something like "AI enabled for 'YourGame' (Claude Code)." — or, if you are not signed in, adds "Author-only mode — sign in to enable publishing."
6. Restart or reconnect your AI app so it picks up the new server. The chip now reads AI · YourGame, and its dot turns green and pulses while the assistant is actively working.

Click Disable on the same row to remove the entry. Only the Vastopia entry is removed; any other MCP servers in that config file are left untouched.

Where the config is written#

The editor merges its entry into whatever is already in the file, never clobbers other servers, and refuses to write at all if the existing file cannot be parsed (it tells you to fix or remove it first).

Other apps: copy the config#

Click Show config for other apps at the bottom of the window to reveal the exact JSON the editor would write, ready to paste into any MCP client's configuration. The entry is keyed vastopia under mcpServers and looks like this on Windows:

{
  "mcpServers": {
    "vastopia": {
      "command": "<editor install folder>/tools/vastopia-mcp/vastopia-mcp-win.exe",
      "args": [],
      "env": {
        "VASTOPIA_PROJECT": "C:/Users/you/VastopiaProjects/MyGame",
        "VASTOPIA_WORKSPACE": "C:/Users/you/VastopiaProjects",
        "VASTOPIA_API_URL": "https://vastopia-api-8a231eb9cc69.herokuapp.com/api",
        "VASTOPIA_ACTOR": "yourusername",
        "VASTOPIA_API_KEY": "…"
      }
    }
  }
}

VASTOPIA_API_KEY is present only when you are signed in and Allow publishing is checked; with it unchecked the editor writes "VASTOPIA_PUBLISHING": "off" instead, which also stops the server from quietly reading your login out of the editor's own files. While the live bridge is running the entry additionally carries VASTOPIA_EDITOR_BRIDGE and VASTOPIA_EDITOR_TOKEN.

The live editor bridge#

Enabling any app while a project is open also starts the editor bridge: a loopback listener on 127.0.0.1 with a per-session token. It is what lets the assistant look at and drive your running editor. You never start it by hand.

• The bridge is re-pointed automatically when you open a different project, so an assistant can never be aimed at the wrong game.
• Disabling the last enabled app stops the bridge.
• A server that was launched before the editor opened finds the bridge anyway through a hot-attach file the editor writes, so the usual ordering (AI app first, editor second) just works.
• With no editor running, bridge-dependent tools report connected: false and explain — that is a normal state, not an error, and every file-based tool still works.

Manual setup#

If you run the server yourself — on a machine without the editor, in a terminal, or pointed at a different API — everything is configured through environment variables. None are required: with nothing set, the server looks for a folder of games near its own location and stops with a message if it finds none.

On startup the server prints one line to its error stream, which your AI app usually shows in its MCP logs:

Vastopia MCP ready. Workspace: C:/Users/you/VastopiaProjects. Active project: C:/Users/you/VastopiaProjects/MyGame. Publishing: enabled (signed in as yourusername).

If the editor login is not being reused you will see Publishing: off (log in via the editor, or set VASTOPIA_API_KEY).

Select a project#

In workspace mode the server starts with no active game unless VASTOPIA_PROJECT is set or exactly one game exists in the workspace. The editor always sets VASTOPIA_PROJECT to the open game, so from the editor you can skip this.

A project created by create_project is a bare skeleton, not a copy of the editor's template: it has no maps, no animation bases and no gameplay systems. Use the editor's New Project wizard (see Create your first game) when you want the template content, then point the assistant at it.

Check editor status and refresh#

These tools close the loop between files on disk and what you see in the editor.

A good first exchange after setup is to ask the assistant to call get_project_summary and get_editor_status. The first proves the server sees your project; the second proves the bridge is up.

Troubleshooting#