Operator MCP

The Operator MCP is the orchestration brain of Revka. It is a Python MCP server (stdio transport) that gives your agent the tools to spawn and coordinate sub-agents, run declarative YAML workflows, manage teams, persist plans and skills in Kumiho graph memory, and talk to other agents over A2A. A companion Session Manager sidecar (Node.js) manages the actual agent SDK sessions and relays their events to the dashboard so you can watch runs live.

Use this page to install the operator, understand how it fits together with the Rust gateway, and learn its resilience, health, and skill mechanics. For the tools the operator exposes once installed, see Spawning & coordinating agents and the workflow guides.

Note

The operator is normally provisioned for you. The first-run onboarding wizard installs the Python MCP sidecars at the end, and you can re-run the installer at any time with revka install --sidecars-only. This page covers both the embedded installer and the source-based make install flow used for development.

Architecture

The Rust daemon spawns a fresh operator MCP process per agent chat session. The operator in turn spawns the Node session manager, which manages agent subprocesses and relays their events back to the gateway WebSocket.

Daemon (Rust binary)
  |
  |-- spawns per-agent-session --> Operator MCP (Python, run_operator_mcp.py)
  |                                  |
  |                                  |-- spawns --> Session Manager (Node.js sidecar)
  |                                  |                |-- manages agent subprocesses
  |                                  |                |-- relays agent events to WS channel
  |                                  |
  |                                  |-- 89 MCP tools (agents, workflows, teams, ...)
  |
  |-- WebSocket <-- agent events <-- Session Manager

Because each chat session gets its own operator process, you do not need to restart the daemon when operator code changes — re-run the installer and start a new chat. You only need to restart the daemon (cargo build --release then restart) when the Rust gateway code or embedded frontend assets change.

Prerequisites

• Python 3.11+ — the operator MCP server.
• Node.js 18+ — required by the session manager sidecar.
• A running Kumiho server — for memory and artifact persistence. Configure it under [kumiho] and verify with revka doctor.

Operator MCP — Python MCP Server

The operator is a stdio-transport MCP server (Server("revka-operator")) exposing 89 tools grouped by domain: agent spawning and lifecycle, agent templates and teams, orchestration patterns, the declarative workflow engine, A2A, inter-agent chat rooms, skills, goals, plans, budget, the system dashboard, and operator-side memory tools.

The daemon locates the operator through the [operator].mcp_path config key, which points at the bootstrap script run_operator_mcp.py. That script installs the operator’s Python dependencies on first launch, then starts the MCP server.

To run the operator directly for debugging:

cd ~/.revka/operator_mcp && python3 run_operator_mcp.py

Caution

requirements.txt must be present at ~/.revka/operator_mcp/requirements.txt. The bootstrap script installs dependencies from it on first launch. If it is missing, the operator crashes on startup and your agent ends up with zero operator tools. Always deploy with the installer rather than copying files by hand.

Session Manager Sidecar (Node.js)

The session manager is a Node.js + TypeScript HTTP server that listens on a Unix socket (avoiding port conflicts). The Python operator talks to it over that socket. It manages agent SDK sessions, relays agent events to the gateway WebSocket channel, and hosts the inter-agent chat service.

Supported agent backends are claude (TypeScript Agent SDK) and codex (Codex AppServer). If the sidecar is unavailable, the operator falls back to spawning agents as direct subprocesses — functional, but with no live event stream.

Caution

The session manager is required for the live execution view. Without it, agents spawn via direct subprocess and no events reach the WebSocket — the dashboard’s live workflow DAG overlay stays empty (no agent.started, agent.tool_use, agent.completed events). See Run the dashboard.

REST API

All endpoints are served on the sidecar’s Unix socket and consumed by the Python operator — you typically interact with them indirectly through MCP tools rather than calling them yourself.

Method	Path	Purpose
POST	/agents	Create an agent session
GET	/agents	List active sessions
GET	/agents/:id	Get agent info
POST	/agents/:id/query	Send a follow-up prompt
POST	/agents/:id/interrupt	Interrupt a running agent
DELETE	/agents/:id	Close and clean up
GET	/agents/:id/events	Get timeline events (query: since=N)
GET	/agents/:id/stream	SSE stream of events
GET	/health	Health check
POST	/chat/rooms	Create a chat room
GET	/chat/rooms	List chat rooms
GET	/chat/rooms/:id	Get room info
DELETE	/chat/rooms/:id	Delete a room
POST	/chat/rooms/:id/messages	Post a message
GET	/chat/rooms/:id/messages	Read messages (query: limit, since)
GET	/chat/rooms/:id/wait	Long-poll for a new message (query: timeout)

The chat endpoints power inter-agent chat rooms: when an agent is @mentioned and the mentioned agent is idle, the session manager injects the message as a follow-up prompt automatically.

[operator] config

The operator is configured under the [operator] section of ~/.revka/config.toml. It is enabled by default and injected into every non-internal agent.

[operator]
enabled = true
mcp_path = "~/.revka/operator_mcp/run_operator_mcp.py"
max_tool_iterations = 80
tool_timeout_secs = 600

Key	Type	Default	Meaning
enabled	bool	true	Disable for deployments not running the Operator MCP sidecar
mcp_path	String	~/.revka/operator_mcp/run_operator_mcp.py	Path to the bootstrap launcher (supports ~ expansion)
max_tool_iterations	u32	80	Overrides agent.max_tool_iterations for operator sessions
tool_timeout_secs	u64	600	Per-tool timeout, capped at 600s; some tools are slow (e.g. Codex image generation ~80–110s)

Operator runtime artifacts live alongside the install:

• Workflow checkpoints: ~/.revka/workflow_checkpoints/
• RunLog JSONL audit trail: ~/.revka/operator_mcp/runlogs/
• Session journal: ~/.revka/operator_mcp/session.ndjson

See the full configuration reference for related [kumiho] and [agent] settings.

Install

There are two paths: the embedded installer baked into the revka binary (recommended for users), and make install from the operator-mcp/ source tree (for contributors).

Embedded installer (recommended)

The revka binary embeds the Operator MCP package at compile time. The installer creates an isolated venv at ~/.revka/operator_mcp/venv/, installs the package and its dependencies, materializes the launcher, and syncs orchestration skills.

# Install both Python sidecars (Kumiho + Operator)
revka install --sidecars-only

# Preview without making changes
revka install --sidecars-only --dry-run

# Pin a specific interpreter
revka install --sidecars-only --python /usr/bin/python3.11

# Opt in to the Node.js Session Manager (requires npm)
revka install --sidecars-only --with-session-manager

Flag	Purpose
--sidecars-only	Required; the full install flow is otherwise handled by install.sh
--skip-operator	Skip the Operator MCP sidecar
--skip-kumiho	Skip the Kumiho MCP sidecar
--with-session-manager	Opt in to installing the Node.js session manager
--dry-run	Print planned actions without executing
--python <path>	Use an explicit Python interpreter
--from-source <repo>	Dev mode: install operator-mcp from a local checkout

Note

The session manager is off by default. When it is not installed, the subprocess fallback runs spawned agents via claude --print and codex exec over OAuth, so spawned agents do not consume API-key spend. The session manager uses the Claude Agent SDK, which requires ANTHROPIC_API_KEY (not subscription OAuth). See Install the Python MCP sidecars.

The binary calls ensure_sidecars_ready transparently on every agent/daemon start, prompting you interactively if the sidecars are missing.

make install / make dev-install (from source)

When working in the operator-mcp/ source tree, use the Makefile. make install is the canonical deployment — it keeps the Python operator, Node sidecar, skills, bootstrap script, and requirements.txt in sync. Do not rsync individual files.

1. Build and install everything to ~/.revka/operator_mcp/:

   cd operator-mcp
   make install

   This runs install-python (creates the venv and pip install '.[all]'), install-ts (builds and copies the session manager dist/), install-skills (copies skills/*.md to ~/.revka/skills/), and install-bootstrap.

2. For iterative development, use the editable install instead. It symlinks the operator package, session manager, and skills so edits take effect immediately:

   make dev-install

3. Start a new agent chat. Since each session spawns a fresh operator process, your changes load without a daemon restart.

Other Makefile targets:

Target	What it does
make build	Build the TypeScript sidecar and check Python syntax
make build-ts	Rebuild only the TypeScript session manager (npm install && npm run build)
make typecheck	Type-check the session manager (tsc --noEmit)
make clean	Remove dist/, node_modules/, build artifacts, and __pycache__

After make install, the operator components live at:

Component	Install path
Python operator	~/.revka/operator_mcp/*.py (+ subpackages)
Session manager	~/.revka/operator_mcp/session-manager/
Skills	~/.revka/skills/
Bootstrap launcher	~/.revka/operator_mcp/run_operator_mcp.py
Python deps manifest	~/.revka/operator_mcp/requirements.txt

Circuit Breaker and Retry Queue

The operator is resilient to the session manager restarting or being temporarily unavailable. It wraps sidecar calls in a circuit breaker (states: closed, open, half_open) and queues failed operations in a retry queue. Three tools expose this state:

Tool	Returns
get_circuit_breaker_status	State (closed/open/half_open), failure count, recovery timing
reset_circuit_breaker	Forces the breaker back to CLOSED after you confirm the sidecar is healthy
get_retry_queue_status	Pending operations, success/failure counts, per-op details

Tip

If the operator reports “sidecar unavailable”, call get_circuit_breaker_status first. Only call reset_circuit_breaker after you have confirmed the session manager has actually recovered — forcing it closed while the sidecar is still down just re-trips it.

System Dashboard

system_dashboard is the quickest single-call health check. It returns a unified snapshot combining active agents, workflow status, a cost summary, Kumiho connectivity, sidecar/gateway health, and team count.

system_dashboard(include_costs?, include_agents?, include_workflows?, include_health?)

All four sections default to true. Call it at the start of a complex session to verify every component — operator, sidecar, gateway, and Kumiho — is available before you spawn agents. Cost limits surfaced here are configured under [cost] in your config; see Cost tracking & budgets. Related health and liveness tools include get_agent_health (detects stuck agents) and get_journal_health (journal size, write latency, rotation status).

Orchestration Skills (shipped with operator)

The operator ships seven Markdown skill guides installed to ~/.revka/skills/ (from operator-mcp/skills/). These teach the agent how to use the operator’s coordination primitives effectively, and are loaded into the agent’s system prompt when relevant.

Skill file	Teaches
operator-orchestrator.md	Chat-room-centric team coordination (“chat room as backbone”)
operator-handoff.md	Agent handoff procedures
operator-loop.md	Iterative refinement loops
operator-committee.md	Group chat / committee decision-making
operator-chat.md	Chat room usage patterns
kumiho-sdk.md	Kumiho memory SDK usage
construct-workflows.md	Declarative workflow authoring

The operator-orchestrator.md skill is the most important — it defines the preferred team coordination model where a shared chat room acts as the backbone for decisions and findings.

Note

These shipped skills are distinct from the runtime Skills system, where agents capture and version their own SKILL.md artifacts in Kumiho via capture_skill. The shipped orchestration skills are static guides; captured skills are learned and reranked by effectiveness.

Verify the install

Run the diagnostics command to confirm the operator and its prerequisites are healthy:

revka doctor

The sidecars and kumiho categories check that the venv interpreters and launcher scripts exist and that Kumiho is reachable. You can also confirm the launcher manually:

ls ~/.revka/operator_mcp/venv/bin/python3
ls ~/.revka/operator_mcp/run_operator_mcp.py

On Windows the venv interpreter is at venv/Scripts/python.exe.

Next steps

Spawning & coordinating agents create_agent, lifecycle tools, teams, and orchestration patterns.

Workflows overview Author and run declarative YAML workflows.

A2A & cloud agents Call external A2A agents and the prebuilt cloud Coder/Reviewer.

Install the Python MCP sidecars Provision Kumiho and Operator venvs from the binary.