Skip to content

AI Assistants (MCP)

The editor has a built-in server for the Model Context Protocol (MCP), the open protocol that AI assistants use to work with other applications. Connect an assistant that supports MCP, such as Claude Code, and it can inspect the open project, build and edit scenes, write and build C# scripts, author procedural graphs, and place robots, while you watch the result in the editor.

The server starts with the editor every time; there is nothing to turn on. This page covers connecting an assistant, what it can do, and how its changes are kept safe.

In short

While the editor is running, it serves MCP over HTTP at http://127.0.0.1:19331/mcp. Add that address to your assistant, for Claude Code with claude mcp add --transport http lucky-engine http://127.0.0.1:19331/mcp, and open a project in the editor. Scene edits the assistant makes can be undone like your own, and its tools for reading and editing project files only work inside the project folder.

Upgrading from 2026.2

The in-editor Agent panel has been removed. To work with an AI assistant, connect it to the editor's MCP server as described on this page.

Before you start

  • The editor must be running. The server lives inside the editor and stops when you close it.
  • Open the project you want to work on. The assistant works on the editor's open project and scene, even while the Welcome screen is showing. That is the project under CURRENT on the Welcome screen, which on a first launch is the bundled Welcome project.
  • Use an assistant that supports MCP over HTTP. Assistants connect to the editor over HTTP.
  • Run the assistant on the same computer. The server accepts connections from this computer only.

Connecting Claude Code

  1. Start the editor and open a project.

  2. In a terminal, add the server to Claude Code. lucky-engine is the name the server gets in Claude Code; you can choose another.

    claude mcp add --transport http lucky-engine http://127.0.0.1:19331/mcp

  3. Start Claude Code and run /mcp. The lucky-engine server should be listed as connected, with its tools.

By default, claude mcp add makes the server available in the folder where you run it. To use it from any folder, add --scope user to the command.

Connecting other assistants

Any MCP client that supports HTTP servers can connect to the same address. Many clients read a JSON configuration like this one:

{
  "mcpServers": {
    "lucky-engine": {
      "type": "http",
      "url": "http://127.0.0.1:19331/mcp"
    }
  }
}

The file this goes in, and the exact key names, differ between clients. Check your client's documentation for adding an HTTP (sometimes called "Streamable HTTP") MCP server, and give it the URL http://127.0.0.1:19331/mcp.

What an assistant can do

The server offers tools in these areas. The assistant picks the tools itself; you describe the result you want.

Area Tools What they do
Inspect the scene get_current_scene, search_entities, get_entity_properties, get_selected_entities Read the open scene's name and path, find entities, read an entity's components and properties, and see what you have selected
Find assets search_assets, get_asset_metadata, get_asset_dependencies, refresh_assets Search project assets by type, folder or name, inspect an asset and what it depends on, and rescan the asset folder
Look at the result capture_viewport_screenshot, capture_scene, capture_scene_camera Take a screenshot of the viewport, render the scene from any position, or render the view of a Camera entity in Edit mode
Build the scene create_entity, create_game_object, duplicate_entity, destroy_entity, batch_destroy_entities, parent_entity, unparent_entity, reorder_child_entity, select_entity, focus_camera_on_entity Create, copy, delete and arrange entities, create shapes such as cubes and spheres with a material and an optional collider, select an entity, and move the editor camera to it
Edit components add_component, remove_component, set_entity_property, batch_set_entity_property, make_mujoco_dynamic_body Add and remove components, change property values on one or many entities, and turn an object into a free-moving MuJoCo body
Create assets create_material, create_prefab_from_entity, import_and_spawn_mesh, update_entity_mesh, spawn_point_cloud Create materials and prefabs, import a GLB or glTF mesh into the scene, replace an entity's mesh, and show a mesh's vertices as a point cloud
Scenes create_scene, open_scene Create a scene with a default camera, sky and ground, or open another scene. Neither replaces a scene with unsaved changes unless asked to; see Undo and safety
Scripts create_script, read_file, write_file, edit_file, build_script_assembly, inspect_script_api Create C# scripts, read and edit files in the project, build the scripts and reload them in the editor, and list the members of a C# type
Robots list_available_robots, spawn_robot List the robot packs in the Content Vault and place one in the scene. A pack that is not installed yet is installed in the background first
Content Vault list_content_packs, create_project_from_pack, content_pack_job List the Content Vault packs with their install state and installation progress, create a new project from a project pack in a folder the assistant names, and follow or cancel that job. The new project is not opened
Procedural graphs graph authoring tools Create and edit procedural graphs, check the geometry a graph produces, and prepare a graph for import into the project
Scene authoring authoring_state, scene_authoring, authoring_import, authoring_import_status, authoring_cooks, authoring_save, authoring_last_result Check that the open scene is ready to edit, import packaged graphs into the project's assets, create graph instances, cameras, lights and empty entities, rename, move, reparent and copy entities, change graph parameters and camera and light properties, wait until the graphs have finished building, and save the scene
Reference search_docs, read_doc Search and read the reference notes about Lucky Engine that ship with the editor

Values follow the engine's conventions: positions in metres, rotations in radians, and +Y up. See Units.

Tips for good results

  • Ask the assistant to read the built-in reference (search_docs, read_doc) and to look up component members (inspect_script_api) before it writes C# code.
  • Ask it to take a screenshot (capture_viewport_screenshot) after placing objects, so it can check its own work.
  • Asking for a robot that is not installed yet starts installing its pack in the background, and spawn_robot places nothing that time. The assistant follows the installation with list_content_packs and asks for the robot again once it has finished. A robot is named by its pack's folder name or its exact display name, as list_available_robots lists them.
  • build_script_assembly builds the project's scripts the same way the editor does, then reloads them. Compile errors go back to the assistant so it can fix them. See Creating and Building Scripts.

Undo and safety

  • Scene edits can be undone. Creating, deleting and arranging entities, adding and removing components, changing properties, and the edits scene_authoring makes go on the editor's undo stack, so Edit → Undo (Ctrl+Z) reverts them like your own edits. A tool call that fails adds nothing to the undo stack.
  • Scene edits are not saved automatically. They change the open scene like your own edits; save with File → Save (Ctrl+S) to keep them.
  • Unsaved changes are not thrown away. create_scene and open_scene refuse to replace a scene that has unsaved changes. Tell the assistant whether to save them or discard them first, or to show the editor's usual save prompt so that you decide.
  • Files are written straight to disk. Scripts, materials, prefabs, new scenes, graph files and packages the assistant creates or changes are saved as files immediately, and Undo does not remove them. Keep your project under version control so you can review and revert these changes.
  • Project file access stays in the project. read_file, write_file and edit_file only work inside the open project's folder and reject paths outside it. The procedural graph tools and create_project_from_pack take full paths instead, and write to the folders the assistant gives them.
  • Only local programs can connect. The server listens only on this computer and has no password, so any program running on your computer can use it while the editor is open.

Ports and several editors

The server uses two ports on 127.0.0.1:

Port Used for
19331 MCP over HTTP, at the path /mcp. This is the address assistants connect to.
19330 A plain TCP port that accepts the same MCP requests as JSON-RPC messages, one per line, for your own scripts.

If one of the ports cannot be used, the MCP server does not start and assistants cannot connect to that editor. Troubleshooting shows how to check that it is running.

To use other ports, start the editor with --mcp <port>, which sets the TCP port. The HTTP port is then the next port up, unless you also pass --mcp-http <port>; the two must differ, and --mcp-http only works together with --mcp. Starting with --mcp also skips the Welcome screen. See Command Line.

To run several editors at once, start each additional editor with its own --mcp port, and point each assistant at the HTTP port of the editor it should use. Editors that share the default ports do not always detect the conflict, and an assistant could then reach either one. For example, an editor started with --mcp 19340 serves MCP at http://127.0.0.1:19341/mcp.

Troubleshooting

The assistant cannot connect

Check that the editor is running, then check the server from a terminal:

curl http://127.0.0.1:19331/healthz

A running server answers {"ok":true}. If there is no answer while the editor is open, the MCP server did not start; see the next section.

The MCP server does not start

Another program is probably using port 19330 or 19331. Close it, or start the editor with --mcp and a free port.

Tools return "No active project" or "No active scene"

Open a project, and a scene in it, then ask again.

Creating or opening a scene is refused

The open scene has unsaved changes, and create_scene and open_scene do not discard them on their own. Save the scene, or tell the assistant to save or discard the changes, then ask again. See Undo and safety.

The assistant changes the wrong editor

With several editors running, each needs its own ports. Start every additional editor with a different --mcp port and connect each assistant to the matching URL.

A long tool call returns an empty result

The editor waits about 30 seconds for a tool call to finish. If the work takes longer, the assistant gets an empty result or a time-out error, but the editor carries on with the work. This can happen with build_script_assembly when the build takes a long time. Before the assistant tries again, ask it to check the outcome, for example the scene with search_entities, so that it does not repeat a change that has already been made.

Installing a robot pack and creating a project from a pack do not run into this limit: they run in the background, and the assistant follows their progress with list_content_packs and content_pack_job.

Where to go next