Driving XGENIA from Claude Code

Early Alpha

The XGENIA MCP server is in early alpha. Tool names and result fields change between builds.

MCP runs in two directions, and it is worth being clear which one this page is about.

Direction	What it means	Where it is documented
Into XGENIA	The Chat panel calls tools on your servers — your API, a docs server, a database	MCP Servers
Out of XGENIA	An outside agent — Claude Code — drives the editor itself	This page

The xgenia MCP server is the second one. It attaches to the running XGENIA desktop app over the Chrome DevTools Protocol and exposes it as 17 tools, so Claude Code can launch the editor, open or create a project, type prompts into the AI Chat panel, read the transcript back, screenshot the canvas, pull the debug export, and restart the app when it wedges.

It drives the app you already have installed. There is nothing to enable inside XGENIA — every build opens a CDP port on 9223.

What you can do with it

• Run a build end to end without touching the editor. Send the prompt, wait for the turn, read what the panel's AI did, screenshot the result.
• Test XGENIA itself. Drive the same flow repeatedly and check what actually happened, rather than what the panel claims happened.
• Debug a session after the fact. xgenia_debug_export pulls the panel's own record — every tool call with its arguments and result, the thinking log, both consoles, the token spend — and xgenia_debug_query greps inside it.
• Watch the live engine. xgenia_runtime_logs reads the running preview's log buffer directly, so you can see which function nodes ran, with what body, right now.
• Recover a wedged editor. xgenia_restart saves, kills the right process tree, relaunches, and reopens the project.

Requirements

Requirement	Detail
XGENIA installed	Or a checkout you can run npm run dev from. No flag or setting to turn on.
Signed in once, by hand	The harness detects the login screen and stops. There is no tool, flag or environment variable that types, stores or reads a password.
XGENIA Pro	The Chat panel the chat tools drive is a Pro feature, with your own OpenRouter key configured. See Getting Started.
Node 18+	For the server process itself.
Claude Code	Or any other MCP client — nothing here is Claude-specific except the plugin packaging.

Install

Two pieces, and today they are installed separately: the server, which provides the tools, and the skill, which teaches an agent how to use them.

Step 1 — The server, from a checkout

The package is not on npm and dist/ is gitignored, so build it once:

git clone https://github.com/XgeniaORG/XGENIA.git
cd XGENIA/packages/xgenia-mcp-server
npm install
npm run build
claude mcp add xgenia -- node "$PWD/dist/index.js"

Restart Claude Code, then check /mcp lists an xgenia server.

Step 2 — The skill

Copy it into your personal skills directory:

cp -r XGENIA/plugins/xgenia/skills/xgenia-mcp ~/.claude/skills/

It loads on the next session, and /xgenia-mcp invokes it directly.

The marketplace install does not work yet

/plugin marketplace add XgeniaORG/XGENIA followed by /plugin install xgenia@xgenia succeeds, and gives you the skill — but not the tools.

A marketplace install copies only the plugin's own directory (.claude-plugin, .mcp.json, bin, skills, README.md). The plugin's launcher expects to sit inside a full XGENIA checkout and resolves ../../../packages/xgenia-mcp-server, which is not in the cache, so it exits before the server starts:

[xgenia-mcp] Cannot find the server at
~/.claude/plugins/cache/xgenia/packages/xgenia-mcp-server.

Use the two steps above until the server is published to npm and the plugin's .mcp.json can become npx -y xgenia-mcp.

npx -y xgenia-mcp appears in some older notes. Neither xgenia-mcp nor @xgenia/mcp-server is published, so that form fails too.

One note on the launcher for whenever it is fixed: its build output goes to stderr deliberately, because stdout is the MCP protocol channel and one stray byte there corrupts the stream and the client drops the server.

Environment

Variable	Purpose
XGENIA_CDP_PORT	Override the debugging port (default 9223)
XGENIA_APP_PATH	Path to an installed XGENIA binary
XGENIA_REPO_DIR	Path to a checkout, for target: "dev"

Launching by hand from an Electron-based IDE

VS Code, Cursor and similar export ELECTRON_RUN_AS_NODE=1 for their own embedded Node. The electron binary then runs as plain Node and XGENIA dies with TypeError: Cannot read properties of undefined (reading 'getVersion'). The harness strips that variable from anything it spawns, so xgenia_launch is unaffected — only a manual launch from such a terminal is. Unset it, or let xgenia_launch start the app.

Your first session

Every tool returns error, tried and hint on failure instead of throwing. hint says what to do next — read it before deciding anything.

xgenia_health                      → running? project open? chat mounted? busy? signed in?
xgenia_launch                      → only if not running
xgenia_open_project { dir | name } → only if no project, or the wrong one
                                     (check the model here — see below)
xgenia_chat_send { text, waitIdle: true, timeoutMs: 300000 }
xgenia_chat_read { since: <last total> }
xgenia_screenshot { region: "chat" } → when the text is not enough

waitIdle: true blocks until the turn finishes and returns idle, waitedMs, timedOut and newMessages. Prefer it over polling in a loop.

For a long build, send with waitIdle: false and poll xgenia_chat_read instead — that way you can stop a run that is going astray rather than paying for it to finish.

Read the transcript incrementally: keep the last total and pass it back as since. Long messages come back truncated; if you need a full one, ask the panel's AI to restate the part you want rather than fighting the truncation.

Check the model before a long run

This is the expensive mistake

One slot build ran on a model nobody chose and cost $94.63 across 29 messages, exhausting the OpenRouter account mid-session. The stored model id was malformed, did not resolve, and the request went out on whatever the live list surfaced.

Before any run longer than a couple of turns:

• Read the model off the panel. It is bottom-left of the chat; xgenia_screenshot with region: "chat" shows it. The header shows a running $ cost for the conversation — watch it.
• Remember that dev and packaged builds have different profiles, and therefore different models. Switching between them switches the model. Re-check after any switch.

The model is stored per profile in editorSettings.json, under settings.aiProvider.providers.openrouter.model:

Build	Path (macOS)
Packaged app	~/Library/Application Support/XGENIA/editorSettings.json
Dev build	~/Library/Application Support/Electron/editorSettings.json

Two rules if you edit it:

• That file contains your OpenRouter API key. Print only the fields you need — never dump the whole file into a transcript.
• Quit XGENIA first, or the running app overwrites your change. EditorSettings is not exposed on window, so there is no in-page way to set it.

Read next

• MCP Tool Reference — all 17 tools, their arguments, and the error codes.
• The xgenia-mcp Skill — the traps that make a working call look broken, and how to recover.
• MCP Servers — the other direction: giving the Chat panel your own tools.