MCP server

Ara's MCP server gives an agent the same engine the editor uses: it can find and read entities, look up components and commands, apply edits, control Play, read diagnostics and ask ara why. The tools are generated from the engine's own catalog of protocol methods, so they always match your engine version. To connect a client, see Connect an agent.

#Three ways to serve it

Over stdio the server keeps one session per connection. Every tool takes an optional session; without it, calls use the session the client began, or one that begins automatically on first use, named after the client. Claude Code shows up as agent:claude-code.

#Tools

A per-project server has 13 tools. The global server has the same 13 plus ara_projects, 14 in all.

Tools with several operations take an action parameter. ara_schema takes list, describe or search; ara_jobs takes list, status, start or cancel; ara_play and ara_session have longer lists, described in their input schemas. Each tool's input schema is generated from the method's parameter types, including the doc comment on every field, so clients see the same descriptions as the method reference.

ara_apply's schema also lists every command with its arguments, so an agent can pick a command without a separate lookup. For details, it calls ara_schema with "action": "describe".

What the tools can do depends on which process owns the project. With the editor open, ara_capture works and ara_session also offers editor.* actions for editor navigation; a headless engine doesn't have them.

#What the server tells agents

When a client connects, the server sends instructions. For a per-project server they are:

Ara game engine tools. ara_session {"action": "begin", "client": "<your name>"} returns a `session` handle and the project's documents; over `ara mcp` the session is optional (one begins on first use). Read scenes with ara_inspect and ara_query; edit only through ara_apply (atomic batches with a `why`; `doc` defaults to the document holding the entities you name). Name entities by ID (`e_8b21`), `$symbol` from an earlier call, or `name:Crate` / `name:Floor/Crate`. Find components and fields with ara_schema {"action": "search"}. Conventions: Y-up, meters, degrees, linear colors, references @path#id. Diagnostics carry stable ARA codes and machine-applicable fixes; when something looks wrong (an entity does not show up, a code you do not know, a slow frame), ask ara_why first: it returns ranked causes with fixes. Other humans and agents may be working in the project at the same time: ara_session {"action": "who"} shows who is doing what and their activity. Changes apply immediately, with overwrite notices and undo per turn. Active human field gestures delay only that field, for at most two seconds.

The global server's instructions are shorter:

Ara Hub: call ara_projects list to see registered projects. Target any tool with project, or bind using ara_session {action: open, project}. Agent changes apply immediately; undo per turn and overwrite notices are available. Only Hub-registered projects are visible.

#Results

A successful call returns the method's text form in content (for example, the same text ara do prints) and the full result as JSON in structuredContent. Methods meant for agents, such as why and logs, keep their results short, since that JSON is what the agent reads.

Engine errors come back with isError: true, the rendered diagnostics and their JSON, including fixes:

error[ARA1610]: agent changes need a `why`: one sentence on the reason, shown to the human who reviews them
  --> why
  = fix: Add a `why`

diagnostics: [{"code":"ARA1610","severity":"error","message":"agent changes need a `why`: one sentence on the reason, shown to the human who reviews them","location":{"path":"why"},"fixes":[{"title":"Add a `why`","action":"set","path":"why","value":"<one sentence: why this change>"}]}]

#Global MCP and Ara Hub

The global server works through Ara Hub's user-level service, which keeps the registry of projects and engine versions. Each open project runs in its own process, either in the editor or headless, so several projects can be open at once.

• Only Hub-registered projects are visible. Register a folder with ara hub add <path> or create one with ara hub create.
• Every tool takes project: the project's ID, unique name or path. Or bind the session once with ara_session {"action": "open", "project": "MyGame"}.
• Sessions never cross projects. A session bound to one project can't edit another.
• Closed projects open on demand. If the agent targets a registered project that isn't open, the Hub starts it headless.

ara_projects actions:

You can manage the same things from the command line with ara hub projects, ara hub status, ara hub open, ara hub close and ara hub activity. ara hub shutdown stops the Hub service; open projects keep running. See the hub CLI reference.

#Per-project MCP

ara mcp --root <project> serves one project with the original per-project server. It's what the .mcp.json from ara init runs. It doesn't need the Hub, and it doesn't have ara_projects.

#The Engine Protocol underneath

The MCP tools are a thin layer over the Engine Protocol: JSON-RPC 2.0 over WebSocket (and optionally stdio) on 127.0.0.1, authenticated with a token stored in .ara. The editor and the ara CLI use the same protocol. ara serve --stdio also serves it on standard input and output. rpc.discover returns the protocol version, the scopes and every method with its parameter schema, and the method reference documents each one.