AI agents (MCP)

RUNOS has a built-in MCP server. It also works without an external agent: the AI assistant is a chat right inside RUNOS with the same tools. MCP (Model Context Protocol) is the open standard AI agents such as Claude Code, Claude Desktop or Cursor use to work with programs. With the server on, your AI agent can read your workflows on this PC, write new ones, check them, run them as a test and start or stop them.

AI agent (e.g. Claude Code) ──▶ http://localhost:47811/mcp ──▶ RUNOS ──▶ workflows

Turning it on

1. Open Settings (gear at the bottom of the activity bar).
2. Under AI agents, turn on MCP server for AI agents. The dot next to it turns green (Running).
3. Under Connect an AI agent, copy the setup for your agent:
   • Copy Claude Code command: run the command in a terminal; Claude Code then knows RUNOS as runos.
   • Copy JSON: the mcpServers entry for agents that read a JSON configuration (e.g. Claude Code’s .mcp.json, Cursor).

claude mcp add --transport http runos http://localhost:47811/mcp --header "Authorization: Bearer <key>"

The server runs while RUNOS is open (also minimized in the notification area) and starts again with RUNOS until you turn it off. It is off by default.

Agents that only start local processes (stdio)

Connect Claude Desktop and other agents that only start local programs through the mcp-remote bridge (needs Node.js): command npx with the arguments mcp-remote http://localhost:47811/mcp --header "Authorization: Bearer <key>".

What the agent can do

Tool	What it does
list_workflows	All saved workflows: id, name, trigger, whether it is running, last run
get_workflow	One workflow with its complete JSON
validate_workflow	Checks a workflow JSON without saving or running it
save_workflow	Saves a workflow JSON: without id as a new workflow, with id over an existing one
edit_workflow	Change parts of a saved workflow without sending the whole JSON: turn an action on or off (Enabled), set a parameter, remove, add or move an action. Actions are found by name, nested ones too. The result is checked like validate_workflow and saved like save_workflow; comments in the JSON are not kept.
run_workflow	Runs the actions of a saved or not yet saved workflow once, right now, like Run in the editor, and returns the result with the log lines of the run
set_workflow_running	Starts or stops a workflow, like Start / Stop in the workflow list
get_logs	Log entries (by default the newest 30): of this session, earlier sessions and, in a shared data folder, the other users (with user); optionally of one workflow, one user or from a level up
list_action_types	The available triggers and actions with their parameter names; with types (e.g. File, SMTP or all) the named ones with each parameter’s description, defaults and output
get_templates	The workflow templates RUNOS offers under New (from the RUNOS server), with name, description and category; with id one template’s complete JSON. Without an internet connection the tool reports an error.
list_connectors	The connectors a workflow can use with {{connector.<Name>.<Field>}}: name, provider, auth type, status, base URL, the matching reference, and whether the owner of a shared data folder shared it. Never keys, passwords or tokens; you create connectors yourself under Connectors.
take_screenshot	A picture of the RUNOS main window as it looks right now (open view, editor tab, dialogs), so the agent sees what you see. Only the RUNOS window, never the rest of the screen. Fails while the window is minimized or in the notification area.

Good to know:

• run_workflow runs the actions for real: mails are sent, files written, documents printed. Let the agent test with harmless values, e.g. your own address. A run is cancelled after timeoutSeconds (default 300 seconds). RUNOS replaces passwords and keys in the result with ***.
• save_workflow only saves workflows RUNOS can load. As when saving in RUNOS, the JSON’s Autostart then decides whether it runs. If the workflow is open in an editor tab, the tab shows the saved version right away, so you watch the change happen. Only while the tab has unsaved changes of yours does RUNOS refuse the save, so your work is not lost; save or undo them first. When RUNOS uses another user’s shared data folder, it refuses the save: only the owner changes those workflows.
• What the agent does is in the log (source MCP, or under the workflow’s name); saved workflows show “(AI agent)” as last editor.

Security

• The server only accepts connections from this PC (localhost), not from the network.
• Every request needs the key. It is per Windows user and stored in %LOCALAPPDATA%\RUNOS\McpKey.txt, so on a terminal server no other user can read it.
• Whoever has the key can run and change your workflows. Do not pass it on. New key creates a new one; agents set up with the old one no longer connect until you copy the setup again.

Troubleshooting

Display / message	Cause and fix
Not running, “Port 47811 is used by another program.”	Another program (or another user’s RUNOS on a terminal server) uses the port. Set another port under "McpPort" in Settings.json in your data folder (default Documents\RUNOS\Config), restart RUNOS and copy the setup again.
The agent reports “Missing or wrong key” (401)	The key was renewed. Copy the setup again.
The agent cannot reach localhost:47811	RUNOS is closed or the server is off. The address must be localhost, not 127.0.0.1.