External AI tools

Claude Code, Codex, Cursor, VS Code, Gemini CLI, Windsurf or Claude Desktop can drive Runeya even when you start them yourself, outside the app: list and start services, read logs, set variables, work on the kanban. They go through Runeya's MCP server, the runeya mcp command.

Before you start

You need a Runeya version that knows this command, installed on your PATH:

runeya --help

The command list must include mcp. Otherwise, update Runeya:

npm i -g @runeya/runeya

Runeya must also be running when the AI tool uses it.

Connecting a tool

From the settings

Settings → AI clients lists the AI tools found on the machine. Connect adds Runeya to the tool's configuration and Remove removes it. Only the runeya entry is changed. Your other MCP servers are not modified.

Then restart the tool, because it reads its configuration at startup.

By hand

The entry calls the runeya mcp command. It holds no secret: access is granted on first use (see below).

Tool	Command or file
Claude Code	claude mcp add --scope user runeya -- runeya mcp
Claude Code, on Windows	claude mcp add --scope user runeya -- cmd /c runeya mcp
Codex	codex mcp add runeya -- runeya mcp
Codex, on Windows	codex mcp add runeya -- cmd /c runeya mcp
Cursor	~/.cursor/mcp.json
Gemini CLI	~/.gemini/settings.json
Windsurf	~/.codeium/windsurf/mcp_config.json
Claude Desktop	claude_desktop_config.json, in Claude's settings folder

In these JSON files:

{
  "mcpServers": {
    "runeya": { "command": "runeya", "args": ["mcp"] }
  }
}

VS Code keeps its servers under servers, in the mcp.json of its user settings:

{
  "servers": {
    "runeya": { "type": "stdio", "command": "runeya", "args": ["mcp"] }
  }
}

On Windows, in these JSON files, replace "command": "runeya", "args": ["mcp"] with "command": "cmd", "args": ["/c", "runeya", "mcp"]: most tools cannot find the runeya command without going through cmd. The Claude Code and Codex commands have their Windows variant in the table above.

Granting access

The first time a tool calls Runeya, it asks for access. Runeya then shows a window with the tool's name, the folder it was started from and a four-digit code. The tool shows the same code on its side.

Check that both codes match, then accept. If you did not start anything, deny. A request with no answer expires after two minutes.

Each tool makes its own request: accepting Claude Code does not give access to Cursor.

Removing access

Settings → AI clients → Granted access lists the tools that were given access. Revoke removes access immediately. The tool must then ask again to continue.

Which project, which instance

When started in a project's folder, the tool works on that project by default. If you ask it for the services, it only lists that project's services. It can still read another project if you name it. When started outside any project, it sees every project on the machine.

If several Runeya instances are running on the machine, the tool asks you which one to use.

What the tool can do

• Services: list them, see their status, logs and resource use, start, stop and restart them. It can also create a service or change its configuration, including switching it to Docker.
• Environment variables: read, add, change and remove them, in a global environment or in a service's own environment.
• Projects and git: read projects, their folders and the git state (status, history, branches, diffs). It runs no git operation.
• Kanban: read boards, cards, comments and attachments, create and edit cards, move, comment and archive them, place a card on another board. It also reads the support conversations linked to a card (Intercom, HubSpot…).

It cannot delete a service, a project or an environment.

Your secrets

The tool does not read the value of a secret, unless you shared it with AI tools (the AI read or AI inject box of the variable). It sees that the variable exists, but the value is replaced with ***.

It can replace a secret's value without reading it, and create a secret variable. It cannot make a secret public or share it with AI tools: those two choices stay yours.

Working on a card

To have an external tool work on a kanban card, load its context with Runeya's work_on_card command, giving the board ID and the card ID:

Tool	Command
Claude Code	/mcp__runeya__work_on_card
VS Code	/mcp.runeya.work_on_card

The tool receives the card, the board's columns, the team's guidelines and the expected ending (move the card if needed, then comment on it). A tool that does not show MCP commands can call the kanban_get_card_context tool, which returns the same context.

The tool receives this context as a regular message. A session started from the card in Runeya receives it as a system instruction. The tool usually follows the context, but less reliably.

What stays reserved to sessions started from Runeya

An external tool can use Runeya's tools. The following features are only available in conversations that Runeya starts itself:

• the card context given from the start, with the team's guidelines as system instructions;
• automatic runs from a kanban column;
• the companion that reviews the work;
• the conversation stored in Runeya and linked to the card;
• starting and following scenarios.

To use these features on a card, start the AI from the card in Runeya.