Reference

MCP Tools

The OpenRig MCP server exposes 17 tools for machine-callable access to topology management, snapshots, discovery, validation, and communication. An agent using MCP can manage entire topologies without touching the CLI.

Setup

The MCP server is hosted by the CLI. Start it with:

rig mcp serve [--port <port>]

Configure your agent's MCP settings to connect to the OpenRig MCP server. All tools return structured JSON suitable for agent consumption.

Topology Lifecycle

rig_up

Boot a rig from a spec, restore from a snapshot, or install from a bundle.

Parameters

source(string, required)Spec path, bundle path, or rig name.

rigRoot(string)Root directory for resolving agent_ref paths.

Returns

Rig ID, node status breakdown, dashboard URL, attach commands.

rig_down

Tear down a running rig. Auto-snapshots before teardown.

Parameters

rigId(string, required)The rig ID to tear down.

Returns

Snapshot ID, restore command.

rig_ps

List running rigs with node count and status summary.

Returns

Array of rig summaries: id, name, node count, status breakdown.

rig_status

Daemon status and connected rig count.

Returns

Daemon health, uptime, rig count.

Snapshots

rig_snapshot_create

Capture a point-in-time snapshot of a running rig.

Parameters

rigId(string, required)The rig to snapshot.

label(string)Human-readable label.

Returns

Snapshot ID, timestamp, restore command.

rig_snapshot_list

List available snapshots for a rig.

Parameters

rigId(string, required)The rig ID.

Returns

Array of snapshots: id, label, timestamp, node count.

rig_restore

Restore a rig from a snapshot. Reports per-node outcome.

Parameters

snapshotId(string, required)The snapshot to restore from.

Returns

Per-node outcome: resumed, fresh, or failed. Attach commands for ready nodes.

Discovery & Binding

rig_discover

Scan for running agent sessions. Groups by naming convention and shared CWD.

Returns

Array of discovered sessions: session name, runtime, CWD, status.

rig_bind

Bind a discovered session to a rig node. Attaches an unmanaged session into an existing topology.

Parameters

discoveredId(string, required)The discovered session ID.

rigId(string, required)The rig to bind into.

node(string)Logical node ID for existing node binding.

pod(string)Pod namespace for new node creation.

member(string)Member name for new node creation.

Returns

Updated rig state with bound node.

Validation & Inspection

rig_agent_validate

Validate an AgentSpec directory. Checks agent.yaml structure, resource references, profile definitions.

Parameters

path(string, required)Path to the AgentSpec directory.

Returns

Validation result: valid/invalid, errors if any, resource and profile summary.

rig_rig_validate

Validate a RigSpec file. Checks pod structure, member references, edge validity.

Parameters

path(string, required)Path to the RigSpec file.

Returns

Validation result: valid/invalid, errors if any, topology summary.

rig_rig_nodes

List the nodes in a running rig with per-node status, session info, and attach commands.

Parameters

rigId(string, required)The rig ID.

Returns

Array of nodes: id, logical ID, session name, runtime, status, attach command.

rig_bundle_inspect

Inspect a .rigbundle archive without installing. Shows schema version, agents, integrity status.

Parameters

path(string, required)Path to the .rigbundle file.

Returns

Schema version, agent list with versions, integrity check results.

Communication

rig_send

Send a message to an agent's terminal. Uses the two-step send pattern: paste text, wait, submit Enter.

Parameters

session(string, required)Target session name.

text(string, required)The message text to send.

verify(boolean)Request delivery verification.

force(boolean)Override mid-task safety checks.

Returns

Delivery confirmation. Verification result if requested.

rig_capture

Capture terminal output from agent sessions. Can target a single session, a whole rig, or a specific pod.

Parameters

session(string)Target session name.

rig(string)Rig name to capture all sessions.

pod(string)Pod name (used with rig) to capture a specific pod.

lines(number)Number of lines to capture. Default: 20.

Returns

Captured terminal output lines per session.

rig_chatroom_send

Send a message to a rig's chatroom. Enables structured inter-agent communication.

Parameters

rig(string, required)The rig name.

message(string, required)The message to send.

sender(string)Sender name attribution.

Returns

Message ID and delivery confirmation.

rig_chatroom_watch

Watch a rig's chatroom for new messages in real time.

Parameters

rig(string, required)The rig name.

Returns

Stream of chatroom messages as they arrive.

Quick Reference

Tool

Purpose

rig_up

Boot / restore / install

rig_down

Tear down (auto-snapshot)

rig_ps

List running rigs

rig_status

Daemon health

rig_snapshot_create

Capture snapshot

rig_snapshot_list

List snapshots

rig_restore

Restore from snapshot

rig_discover

Scan for sessions

rig_bind

Bind session to rig node

rig_agent_validate

Validate AgentSpec

rig_rig_validate

Validate RigSpec

rig_rig_nodes

List rig nodes

rig_bundle_inspect

Inspect bundle

rig_send

Send message to terminal

rig_capture

Capture terminal output

rig_chatroom_send

Send chatroom message

rig_chatroom_watch

Watch chatroom

Typical Agent Workflow

An agent using MCP tools follows the same product loop as the CLI:

# 1. Boot a topology
rig_up { "source": "auth-rig.yaml", "rigRoot": "." }

# 2. Check status
rig_ps {}

# 3. Inspect nodes
rig_rig_nodes { "rigId": "abc123" }

# 4. Communicate with agents
rig_send { "session": "auth-agent", "text": "run the test suite" }
rig_capture { "session": "auth-agent", "lines": 50 }

# 5. Snapshot before changes
rig_snapshot_create { "rigId": "abc123", "label": "pre-refactor" }

# 6. Tear down when done
rig_down { "rigId": "abc123" }

# 7. Restore later
rig_up { "source": "auth-feats" }