MANUAL / AI assistants / AI assistants over MCP

AI assistants over MCP

The official KroysMcp plugin exposes the editor and the engine through the Model Context Protocol, so an AI assistant can look through a project, make undoable changes, build scripts and read the errors - in the running editor or in a headless engine process.

Delivered asAn optional plugin (KroysMcp)

ProtocolMCP 2025-06-18

ConnectionThis machine only

What it is for

The Model Context Protocol (MCP) is an open protocol that lets AI assistants call tools in other programs. With the KroysMcp plugin enabled, an assistant connected to your editor works with your project the way you do: it finds things in a scene, adds and changes entities, components, materials, prefabs and scripts, builds the scripts and reads what went wrong. It helps with everyday changes and with bringing existing games into the engine.

The plugin ships with the engine in <engine>/Plugins/KroysMcp and is off until a project turns it on. Any MCP client works; nothing else needs to be installed.

Connect the running editor

Tools › Plugins › Plugin Manager..., find KroysEngine MCP Server and turn it on for the project, then restart the editor.
Open Window › MCP Server. It shows the address (http://127.0.0.1:47860/mcp unless that port is taken) and a token that is new every time the editor starts.
Press Copy client config and paste it into your MCP client's server list, or copy the URL and the token separately. The same values are in <project>/Saved/KroysMcp/connection.json while the editor runs.

The editor speaks Streamable HTTP: one POST /mcp per message, answered as JSON or, while a tool runs, as an event stream with progress. New token in the panel (or Tools › Plugins › MCP › Restart MCP Server) ends every client session and starts again with a new token.

Client configuration (HTTP)

{
  "mcpServers": {
    "kroys-engine": {
      "type": "http",
      "url": "http://127.0.0.1:47860/mcp",
      "headers": { "Authorization": "Bearer <token from the MCP Server panel>" }
    }
  }
}

Connect a headless project

For an assistant that works on a project without the editor open, start KroysMcp.exe (next to the editor) over standard input and output (stdio). It opens the project and its startup scene without a window and stops when the client closes the connection.

Option	Meaning
`--project <file>`	the `.kproject` to open (required)
`--scene <file>`	a scene other than the startup scene (content-relative or absolute)
`--approve deny`	tools that delete or write files are refused (default; nobody is there to ask)
`--approve allow`	those tools run without asking

Headless sessions have no Play mode, and changes stay in memory until a tool saves them (scene_save).

Client configuration (stdio)

{
  "mcpServers": {
    "kroys-engine": {
      "command": "C:/KroysEngine/KroysMcp.exe",
      "args": ["--project", "C:/Games/MyGame/MyGame.kproject", "--approve", "deny"]
    }
  }
}

What an assistant can do

Tool	What it does
`project_info`	the project, its folders, the open scene, Play state and the connection
`scene_hierarchy`, `scene_search`	the entity tree; find entities by name or component
`entity_get`	one entity with its transform, children, components and field values
`component_types`	the component types and their fields (type, range)
`entity_create`, `entity_rename`, `entity_reparent`, `entity_delete`	add, rename, move and delete entities
`component_add`, `component_remove`, `field_set`, `transform_set`	change components and reflected fields; values are checked against the field type
`prefab_instantiate`	place a prefab
`edit_undo`	undo or redo, like Edit › Undo
`asset_search`, `asset_info`	find assets by path, name, type or folder
`material_create`, `material_edit`	new materials; base color, metallic, roughness, emission and more
`import_file`	import a model, texture or sound into a content folder
`script_list`, `script_read`, `script_write`	the project's C# scripts
`scripts_build`	build the scripts; errors and warnings with file, line and column
`console_read`	the Console, new lines only if you pass the last sequence number
`play`	start, stop or check Play mode
`package_game`	package the game with the saved profile, with progress; it can be cancelled
`docs_search`, `docs_read`	this documentation

Every tool describes its arguments with a JSON schema. The plugin also offers resources (kroys://project, kroys://scene, kroys://console, kroys://entity/<id> and every manual page as kroys://docs/<page>) and two prompts: describe the open scene, and port a script to a KroysEngine C# script.

Safety

Every scene or material change is one undo step named MCP: <tool>, so Ctrl+Z takes it back like any edit of your own.
Tools that delete or write files (entity_delete, component_remove, material_create, material_edit, import_file, script_write, scene_save, package_game) wait for you: the MCP Server panel shows the request with Allow once, Allow for session and Deny, and a notification tells you it is waiting. Nothing modal opens.
Policy in the panel: ask (default), always allow or always deny those tools, and what happens when no one can answer (automated runs deny unless you allow it).
The editor listens on 127.0.0.1 only. Requests need the token, a local Host and, when a browser sends one, a local Origin; anything else is refused. Requests are limited in size (4 MB) and in number (600 a minute); both limits are in the panel's Policy.
The plugin's manifest declares what it may touch (scene.read, scene.write, assets.write, network.loopback, project.build); remove a permission and the tools that need it disappear.

Protocol details

KroysMcp implements MCP revision 2025-06-18 and also accepts clients that ask for 2025-03-26 or 2024-11-05. It supports initialize, ping, tools/list, tools/call (structured results, progress notifications, cancellation with notifications/cancelled), resources/list, resources/templates/list, resources/read, prompts/list, prompts/get and logging/setLevel. Over HTTP, Mcp-Session-Id names the session after initialize and DELETE /mcp ends it; the server sends no messages outside a request, so GET /mcp is refused. JSON-RPC batches are not accepted.

KroysEngine 0.1.0 documentation, built from the engine repository by Tools/BuildDocsSite.py.