MCP Tool Reference

Early Alpha

The XGENIA MCP server is in early alpha. Tool names and result fields change between builds. See Driving XGENIA from Claude Code for install and setup.

Seventeen tools. None of them throw: a failure comes back as error, tried and hint, where tried names what was attempted and hint says what to do next.

Health and diagnostics

xgenia_health

No arguments. Call this first.

Reports whether XGENIA is running, whether it is the dev or packaged build, which project is open, whether the AI Chat panel is mounted, how long it has been generating, and whether anyone is signed in.

It never fails just because the editor could not be reached — it returns running: false with a code instead:

code	Meaning
not-running	Nothing is listening on the CDP port
editor-unresponsive	Something is listening, but it never became usable — a wedged renderer

That distinction decides your next call: xgenia_launch for the first, xgenia_restart with force for the second.

busyForMs is a floor, not a duration

It is measured from this server process's first sight of the busy state, not from when generation began — the underlying tracker is in-memory and has no earlier signal. A panel stuck for hours looks identical to one that started a second ago. Never report it as "it has been running for N ms".

authenticated is "unknown" rather than a confident true whenever pageResponsive is false. window.ProjectModel is defined by XGENIA's router before the app decides whether anyone is signed in, so it is present on the login screen too — nothing else in the result implies a session.

xgenia_probe

No arguments. Reports which of the DOM selectors the harness depends on currently resolve.

Selectors are contracts with code this server does not own, and the Chat panel deploys independently of XGENIA releases. Run this on any selector-missing to see what moved.

Lifecycle

xgenia_launch

Argument	Type	Notes
target	"app" | "dev" | "auto"	app = the installed build, dev = npm run dev from a checkout, auto prefers whichever is available

Attaches to a running XGENIA, or starts one. If the editor comes up sitting at the login screen, it returns not-authenticated rather than a false success.

xgenia_restart

Argument	Type	Notes
force	boolean	Skip the connect and every in-page read; go straight to the kill

Saves, kills, relaunches, and reopens the project that was open. Refuses while a turn is in flight unless force is set, because that turn would be lost.

Check more than restarted and project:

Field	Why it matters
recoveryError	Why the project failed to reopen. project is null, but the reason survives instead of being swallowed
declinedPorts	Dev ports still occupied that the harness refused to free, because their owner was outside the process tree it killed
hardKilled	true means SIGTERM's grace period expired and SIGKILL was needed — unflushed state, such as an auth session, may be gone
targetSource	Which of connect / process / recovery / unknown supplied the relaunch target, so a silent build switch is visible

Under force, the honest gaps are reported rather than guessed: project: null, the save unconfirmed with reason: "unresponsive", and inFlightTurnLost: "unknown".

A restart clears the chat transcript

Anything the panel's AI needs to know has to go into the next prompt.

xgenia_quit

Argument	Type	Notes
force	boolean	As above

The same safety sequence as xgenia_restart, without the relaunch. Nothing is running afterwards and no project is reopened — xgenia_launch brings XGENIA back, and it starts with no project open.

Projects

xgenia_project_status

No arguments. Which project is open. When none is, it also returns the 25 most recent, so you can pick one.

xgenia_open_project

Argument	Type	Notes
dir	string	Absolute path. A directory not in the recents list is added first
name	string	Open by name instead
openChatIfClosed	boolean	Default true — open the Chat panel from the sidebar if it is not showing

Verifies the editor actually landed on that project rather than trusting the click. On timeout it reports which state the page was really in — the login screen (not-authenticated), a projects screen with zero tiles, or an editor holding a different project — instead of a bare selector-missing.

chatReady: false does not mean the open failed. It means the panel is not usable yet: still mounting, genuinely closed, entitlement-gated, or the open attempt itself failed. chatUnavailable / chatError carry the reason, and chatOpenAttempt — present only when an attempt was made and did not succeed — carries every sidebar tooltip label it saw.

xgenia_new_project

Argument	Type	Notes
name	string	Required
dir	string	Defaults to a sibling of the most recently opened project
openChatIfClosed	boolean	As above

Creates a directory with a fresh, empty project.json — one root Group node, no components beyond /App — and opens it. It refuses rather than overwrites when the resolved directory already exists and is non-empty.

Returns everything xgenia_open_project does, plus createdDir. Every brand-new project opens with the Chat panel hidden, which is why the panel is opened for you by default.

xgenia_close_project

Argument	Type	Notes
force	boolean	Proceed even when the save cannot be confirmed

Saves and returns to the projects screen. There is no clickable exit control for the harness to target, so it saves, reloads the page, and waits for a project tile — which discards any unsaved work the save did not capture.

The AI Chat panel

xgenia_open_chat_panel

Argument	Type	Notes
timeoutMs	number	How long to wait for the panel to render

Normally unnecessary — the open and new project tools already do this. Use it when someone toggled the panel shut by hand, or when you deliberately passed openChatIfClosed: false and now want it.

The button carries no id, aria-label or test id, only a tooltip, so the harness hovers every icon in the left rail and matches "Chat" case-insensitively. On failure it reports reason (no-chat-button or clicked-but-not-rendered) plus labelsSeen — exactly what a maintainer needs if the button is ever renamed.

xgenia_chat_send

Argument	Type	Notes
text	string	Required. The prompt
waitIdle	boolean	Block until the turn finishes
force	boolean	Send even though a turn is in flight
timeoutMs	number	Bound on the wait

Returns only after confirming the input cleared and the transcript advanced. Refuses mid-generation unless force is set.

Never resend on a bare timeout

Read the transcript first. An unconfirmed send comes back with a code that tells you which case you have — and resending the wrong one runs a second paid turn on the same request.

Code	Meaning	Do
render-lag	Sent, not yet painted — usually a panel still booting	xgenia_chat_read. Do not resend
not-submitted	Still sitting in the input, never submitted	Resend. Safe

xgenia_chat_read

Argument	Type	Notes
since	number	Index to page from — pass back the previous total
limit	number	How many messages

Long messages are truncated. The message count and busy flag come from the live panel.

xgenia_chat_wait_idle

Argument	Type	Notes
timeoutMs	number	Defaults to 300000 (5 minutes)

Blocks until the panel stops generating. On timeout it returns timedOut instead of throwing, so you can screenshot and decide.

Screenshots

xgenia_screenshot

Argument	Type	Notes
region	"full" | "chat" | "canvas"	Whole window, the conversation, or the graph
format	"jpeg" | "png"

Returns the image plus cssSize, imageSize, contentSize and scale.

Image pixels are not all page

imageSize is the whole buffer. contentSize is the part the editor is actually drawn in, anchored top-left.

The editor runs at an Electron zoom factor, and the capture surface is allocated at the display's backing scale rather than the zoomed one — so at zoom 0.8 the buffer comes back 25% wider than the page and the last 20% of it is blank.

• Convert any coordinate you read off the image through scale before using it.
• When note says the image is padded, treat anything beyond contentSize as empty space, not as editor UI that failed to render.
• When note says cropped — the editor is zoomed in past the surface — the right and bottom of the page are genuinely missing from the image.

Debug export and live logs

xgenia_debug_export

Argument	Type	Notes
reuseExisting	boolean	Summarise the newest export already on disk instead of producing a fresh one
timeoutMs	number
copyTo	string	Keep a copy somewhere a Downloads clear-out will not reach

Clicks the Chat panel's Debug Export and returns the file path plus a census of what the AI actually did.

The bundle is the only record of the panel AI's own run: every tool call with its arguments and result, the thinking log, the raw API history, both consoles, and the token spend. One slot build produced 7.2MB and 640 tool calls — so this never returns the bundle itself. It returns file, which tools failed with which codes, the top editor errors, and the cost.

A result counts as a failure only when its envelope says ok: false or result.success: false. Prose and condenser-pruned results are reported separately as unparsedResults / prunedByCondenser, because counting those as failures inflated one real census from 77 to 382.

xgenia_debug_query

Argument	Type	Notes
section	enum	Default toolCallSummary
grep	string	A JavaScript regular expression, searched against the serialised entry
ignoreCase	boolean	Case-insensitive by default
tool	string	Filter to one tool name
failuresOnly	boolean	Combine with tool to answer "which calls to X failed and why"
limit / offset	number	Paging
clip	number	Per-entry clip length
file	string	Defaults to the newest export on disk

Sections: toolCallSummary, thinkingLog, visibleChat, rawApiHistory, errors, errorsBeforeSession, consoleLogs.viewer, consoleLogs.editor, subAgents, taskTracking.

It returns matched alongside returned, so a truncated answer is visible rather than silent.

xgenia_runtime_logs

Argument	Type	Notes
grep	string	Regular expression
ignoreCase	boolean
tail	number	Last N entries
clip	number	Per-entry clip length

Reads the running preview's own log buffer (window.XgeniaRuntimeLogs) with no export step. This is what the game actually did, live: which JavaScript function nodes ran and with what body, reel-controller latches such as "stop signal arrived before spin", and every runtimeEval request the panel sent.

It answers questions about the current state, rather than about whenever someone last clicked export. It addresses the preview iframe by URL, so it cannot be answered by the empty cloudruntime page that also exists in the process — the surface that makes the panel's own runtime tools report a mounted game as not_mounted.

The buffer resets when the preview reloads.

Error codes

Code	Meaning
not-running	Nothing is listening on the CDP port at all
no-editor-page	Connected over CDP, but no page matched the editor's URL
not-authenticated	The editor is up, but sitting at the login screen. Stop and tell the user — a human signs in once, in the editor
editor-unresponsive	Something is listening, but the connection or page never became usable
busy-refused	An AI turn is in flight (or its state could not be determined) and force was not set
save-unconfirmed	The pre-kill or pre-close save could not be confirmed and force was not set
selector-missing	A DOM selector did not resolve in time. Run xgenia_probe
project-dir-missing	The requested directory or name could not be resolved, or is invalid
project-mismatch	A tile was clicked, but the editor did not end up reporting that directory as open
chat-frame-missing	The AI Chat panel iframe is not present
recovery-read-failed	The pre-kill recovery snapshot could not be read back after relaunch
timeout	A bounded wait elapsed
page-unresponsive	Fallback for an uncaught exception with no more specific code

Read next

• The xgenia-mcp Skill — the traps, the recovery table, and how to verify a panel change actually reached the running editor.
• Driving XGENIA from Claude Code — install, environment, and the cost rule.