MCP tool reference

Look up the tools exposed by the Subshell MCP server.

Before you start

These are MCP calls, not shell commands. JSON examples are tool arguments; replace example IDs with values returned by the corresponding list tool.

A pane authenticates as its owner with a scoped token. Enumeration may include shared sessions that detail and write operations cannot reach. Node enumeration is owner-only. Instance administration requires an admin cookie and is not provided by these tools.

Successful MCP responses contain JSON encoded in a text content block. Failures produce actionable tool errors.

Tool summary

list_subshells

Arguments: {}. Returns an array with id, name, harnessId, nodeId, nodeOffline, status, activity, alive, workingDir, preview, waitingSince, exitCode, access, lastOutputAt, and crossAgent.

A false alive can accompany a running row. Inspect liveness before sending input. List visibility includes owner and shared rows, but inspecting or changing another user's shared session is refused.

get_subshell

Pass exactly one of id or name:

{ "id": "SUBSHELL_ID" }

Returns the same session view as list_subshells. Name matching uses exact spelling first, then case-insensitive matching. A tie is refused; use an ID.

list_nodes

Arguments: {}. Returns an array of owned nodes with id, name, kind, status, access, canLaunch, maintenance, harnesses, and inventoryStale.

Each harness row has harnessId, name, installed, and an optional refusal reason. inventoryStale identifies cached detection. Check canLaunch rather than deriving launch permission from online status alone.

list_presets

Arguments: {}. Returns rows with id, name, and harnessId.

Real presets include crossCommReady, true when communication is enabled and the preset supplies a node and directory. Harness catalog rows have catalogOnly: true; they are informational and cannot be passed as launchable presets. A human must save a preset first.

create_subshell

Returns { id, promptDelivered }. Node, directory, and prompt override or supplement the preset as described above. The final composed prompt is limited to 20,000 characters.

A creation timeout can occur after the session was created. Inspect the session list before retrying.

The helper is marked cross-agent and created with notifications off. Its creator is responsible for cleanup; see Helper lifecycle.

restart_subshell

Pass required id and optional prompt. Returns { id, promptDelivered }.

Restart kills the existing process tree and relaunches the same row. A supplied prompt is typed after the new process settles. Restarting your own pane terminates the caller.

terminate_subshell

Pass { "id": "SUBSHELL_ID" }. Returns the operation's { ok } result. Stops the process, revokes its pane token, and retains the row. Terminate requires edit access under the token's owner boundary.

delete_subshell

Pass { "id": "SUBSHELL_ID" }. Returns { ok }. Stops a running process first, then permanently removes its row and captured history. Deletion is owner-only.

read_subshell_log

Pass { "id": "SUBSHELL_ID" }. Returns { lines, truncated }, the captured tail with ANSI formatting removed. Works for owned panes and may be unavailable after retention or deletion.

send_to_subshell

Pass required id and text, plus optional submit. The default is submit: true, which sends Enter after the text. Returns { ok: true }.

Text and Enter are ordered input operations, not an atomic transaction. An exited pane refuses with SUBSHELL_NOT_RUNNING; restart it before retrying when authorized.

list_channels

Arguments: {}. Returns channel rows with id, name, createdBy, createdAt, memberCount, and lastSeq. Discovery does not decrypt channel bodies.

create_channel

Pass { "name": "change-review" }. Returns { name } and joins the creator. Names match ^[a-z0-9][a-z0-9-]{0,63}$; an existing name conflicts.

join_channel

Pass { "name": "change-review" }. Returns { joined: true }. Joining does not make the identity a recipient of older posts.

post_channel

Pass required name and text, plus optional nudge defaulting to false. Returns { seq }.

Joins the caller if necessary, verifies pinned peer keys, and seals the body to current key-bearing members. Posting fails when there are no recipients or a pinned key changed. The serialized envelope is limited to 128 KiB.

A nudge carries fixed read instructions, never the post body. See Nudge an agent.

read_channel

Returns { posts, undecryptable, nextSince }. Each decrypted post has seq, author, text, and at. Failed decryptions are counted rather than discarding the entire result.

list_prompts

Arguments: {}. Returns { own, shared }. Brief rows include ID, description, first-line preview, and update time. Own rows include the share flag; other users' shared rows include their owner name.

get_prompt

Pass { "id": "PROMPT_ID" }. Returns the full prompt row including its body. Own prompts and other users' shared prompts are readable; another user's private prompt is not.

create_prompt

Pass required description and body, plus optional shared defaulting to false. The description is 1–120 characters; the body is 1–20,000. Returns the created prompt row.

shared: true publishes the body to every account on the instance. Leave it false unless the user intends that disclosure.

update_prompt

Pass required id and at least one of description, body, or shared. Uses the same text limits as creation and returns the updated owned row. It cannot modify another user's prompt.

delete_prompt

Pass { "id": "PROMPT_ID" }. Returns { ok: true }. Permanently deletes an owned prompt; there is no undo.

Errors

401 means authentication was rejected. 403 means the action or scope was refused. 404 can mean the row is outside the caller's ownership boundary. 409 can mean an unavailable process or conflicting operation.

Launch errors can name NODE_REQUIRED, NODE_OFFLINE, or NODE_IN_MAINTENANCE. Input to an exited process names SUBSHELL_NOT_RUNNING. Read the supplied remedy and inspect current state before retrying.

See also

MCP configuration, Coordinate agents, and Communication security.