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 uses a scoped token to act as its owner. Session lists can include shared sessions that the pane can't inspect or change, while node lists include the machines the account owns or that are shared with it. These tools don't provide instance administration, which requires an admin cookie session.
Successful MCP responses contain JSON encoded in a text content block. Failures produce actionable tool errors.
Tool summary
| Tool | Purpose |
|---|---|
list_subshells | List visible sessions and output previews. |
get_subshell | Inspect one session. |
list_nodes | List machines the account owns or shares, harness health, and SSH and Web previews & screens settings. |
get_node | Inspect a machine from list_nodes and check display prerequisites. |
transfer_node | Hand an owned machine to another account (needs the nodes:transfer grant). |
list_subshell_views | Discover a subshell's apps, browser, and virtual display. |
open_subshell_view | Create a private app or screen connection. |
watch_subshell_browser | Start or stop watching browser frames. |
set_subshell_display | Turn a live subshell's virtual display on or off. |
list_presets | List saved agent presets and harness catalog entries. |
create_subshell | Launch from a saved preset, or open a plain terminal without one. |
restart_subshell | Revive a session in place. |
terminate_subshell | Stop the process and keep the session record. |
delete_subshell | Remove the session and captured history. |
read_subshell_log | Read the tail of captured pane output. |
send_to_subshell | Type into a live owned session. |
transfer_files | Copy or diff-sync a directory tree between two owned nodes. |
exec_in_terminal | Run one command in a terminal pane with its exit code. |
list_channels | Discover channels. |
create_channel | Create a channel and join it. |
join_channel | Join an existing channel. |
post_channel | Seal a message to current members. |
read_channel | Retrieve and decrypt addressed messages. |
list_prompts | List own and shared saved prompts. |
get_prompt | Read a prompt's full text. |
create_prompt | Save a prompt for the pane's owner. |
update_prompt | Edit an owned prompt. |
delete_prompt | Remove an owned prompt. |
list_subshells
Arguments: {}. Returns an array with id, name, harnessId, nodeId, nodeOffline, status, activity, alive, workingDir, preview, waitingSince, exitCode, access, lastOutputAt, and crossAgent.
A session can have status: running even after its process exits, so check alive before sending input. The list includes your own and shared sessions, but you can't use a pane token to inspect or change another user's shared session.
get_subshell
Pass exactly one of id or name:
{ "id": "SUBSHELL_ID" }Returns the same session view as list_subshells. Names match exact spelling first, then ignore case. If more than one session matches, use its ID.
list_nodes
Arguments: {}. Returns an array of machines the account owns or that are shared with it, with id, name, kind, status, access, canLaunch, maintenance, harnesses, and inventoryStale.
os and arch identify the operating system and CPU architecture. systemSpecs contains osRelease, cpuModel, logicalCpuCount, totalMemoryBytes, and reportedAt. These are host capacities, not current free resources or container quotas. Offline nodes retain their last report; a null report means the node hasn't supplied specs. capabilities lists node protocol features, while harnesses describes available agent software.
crossCommNotes contains user-authored context about the node. recommendedStartingDirs lists suggested absolute paths. These suggestions don't grant or restrict directory access; launch permissions still apply. Read the guidance before choosing a node or working directory.
Each harness row has harnessId, name, and installed, plus version, refusal reason, broken, restartRequired, and checkedAt when reported. A broken plugin can't launch even if its binary is installed. restartRequired concerns the server's loaded plugin, not the harness binary. inventoryStale identifies cached detection. Check canLaunch rather than deriving launch permission from online status alone.
webPreviewsEnabled reports permission for web previews; virtualDisplayEnabled reports permission for virtual displays. virtualDisplayProviders lists enabled provider IDs, and virtualDisplayProvider names the default. These fields, sshEnabled, and sshWideForwards report configuration, not live readiness. protocolVersion, agentVersion, and held describe the daemon connection when reported. Missing fields from older servers mean unknown, not disabled. Subshell SSH still requires a browser session; these tools don't grant SSH access or change node settings.
get_node
Pass { "node": "NODE_ID" }, or an unambiguous node name. Returns the same fields as list_nodes, plus virtualDisplay readiness: ready, missing-programs, unsupported, or unavailable. A completed probe includes supported, unmet missing requirements, the checked provider, and enabled for that provider’s node permission. Pass provider to check a specific choice; otherwise the node default is checked. Pass check_display: false to skip the live probe and return unchecked.
For BetterDisplay on macOS, enabled describes node policy, not local helper
consent. missing-programs can include a disabled helper or missing macOS
permissions as well as missing software; read the missing list. MCP cannot
enable the helper or grant those permissions. Follow
macOS helper setup on that node.
A ready display check means its requirements are met. Virtual displays and the chosen provider must also be enabled, the node must permit launches, and launch performs its own checks. get_node addresses the machines list_nodes returns, and the display probe resolves them as the account does: a machine shared with the account, or the server host under its launch grant, can be checked like any other. Node configuration (settings, SSH, shares) still needs the account's own machine.
transfer_node
Pass { "node_id": "NODE_ID", "to_user_id": "USER_ID" }, with node_id an id or exact name from list_nodes and to_user_id the receiving account's id (ids, not e-mails). retain_access_as_manager is optional; when true or omitted, this pane's account stays a Manage grantee on the machine it gave away, and passing false leaves no grant behind.
The tool needs a credential carrying the nodes:transfer permission plus nodes:read: the machine is looked up by id or name through the node list before the handover. A scoped automation key, or a pane launched from one, qualifies; an ordinary pane token gets a refusal that names the door. The handover is one audited transaction; the machine's connection, running subshells, and every other share are unaffected, and re-registration keys minted for the node but never used stop working. Only nodes this pane's account owns are reachable, and the server's built-in node is never transferable. The dashboard procedure and the CLI verb are in Transfer a node.
list_subshell_views
Pass { "subshell_id": "SUBSHELL_ID" }. Returns discovered ports, cdpPort, screen, nodeEnabled, and availability reasons when present. A subshell's virtualDisplay field in list_subshells and get_subshell also identifies its allocated display when reported.
open_subshell_view
For an app, pass { "subshell_id": "SUBSHELL_ID", "kind": "app", "port": 3000 }. For a virtual display, pass { "subshell_id": "SUBSHELL_ID", "kind": "screen" }; the tool uses that display's actual port.
Returns proxyBase, a private capability path relative to the server URL, plus kind, port, and usage guidance. An app path serves HTTP; a screen path carries the viewer's WebSocket protocol and isn't a web page. The call doesn't launch a program or open a workspace tab. Use the dashboard's Web previews & screens picker to open tabs.
Treat the complete link as a secret. Anyone holding it can use the connection while it's valid, and closing a tab doesn't revoke it. Delete temporary helper subshells when finished; see Web previews & screens.
watch_subshell_browser
Pass { "subshell_id": "SUBSHELL_ID", "on": true }, optionally with a CDP port, to start watching browser frames. Pass on: false to stop watching when finished. Frames go to authorized dashboard live subscriptions, not the MCP response. This doesn't provide mouse or keyboard input. The server checks ownership, the node’s web-preview permission, and the browser port, as it does for dashboard requests.
set_subshell_display
Pass { "subshell_id": "SUBSHELL_ID", "screen": { "width": 1280, "height": 800 } }, optionally with a provider ID, to give a running subshell a virtual display. Leave provider out to use the node default. Pass { "subshell_id": "SUBSHELL_ID", "screen": null } to take the display away. Width and height are integers from 320 to 4096. Setting a display returns { ok, screen }, and clearing one returns { ok, closed }, where closed tells you whether a display had actually been running.
You can't hand a running process a new screen, so turning the display on restarts the subshell in place. It keeps its ID and its history, and the conversation comes back only if the harness can resume it. That means an agent turning on its own display ends this tool call with the restart, the way restart_subshell does; how the pane comes back is up to the harness. Turning the display off happens right away and leaves the pane running, though a program that was already running keeps its old display setting until the next restart. Both requests fail while the node is offline, and an offline refusal changes nothing. If a restart is already running, the enable refusal keeps your request: call the tool again once that restart settles and the display applies. Run get_node first to see whether the node has a display provider ready.
list_presets
Arguments: {}. Returns agent presets and harness catalog entries with id, name, and harnessId; SSH presets are dashboard-only and never appear here. Presets switched off in the dashboard aren't listed.
Real presets include crossCommNotes for user-authored guidance, plus nodeId and workingDir for their saved launch defaults. Notes help the calling agent choose a preset; they aren't appended to the launched subshell's prompt.
Real presets include crossCommReady, true when communication is enabled and the preset supplies a node and directory. Harness catalog rows have catalogOnly: true; an agent harness catalog row is informational and needs a human to save a preset before it can launch, but a plain terminal harness can launch presetless straight from create_subshell.
create_subshell
The tool has two shapes. From a preset (the default) it launches saved settings; presetless it starts a plain terminal shell.
| Argument | Requirement | Meaning |
|---|---|---|
preset | Optional string | Saved preset ID from list_presets. Omit for a presetless terminal launch. |
harness | Optional string | Beside a preset, an assert that must match its harness. Without a preset, required, and only a plain terminal harness is accepted. |
name | Optional string | New subshell display name. |
node | Optional string | Node ID or unambiguous display name override. |
working_dir | Optional string | Absolute directory on that node. Omitted, a presetless terminal starts in the node's home. |
prompt | Optional string | Task text added to or replacing the preset prompt, or typed once a presetless shell settles. |
screen | Optional object or null | Display width and height (integers from 320 to 4096) and optional provider ID. Omit to inherit the preset’s display, or pass null for no display. |
prompt_mode | Optional enum | append by default, or replace. Needs a preset. |
Before requesting a display, use get_node to check its requirements and
permission. An omitted provider uses the node default. Creating a subshell
doesn't enable providers or install missing programs.
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. See Terminal sessions for driving a shell pane with send_to_subshell and the read_subshell_log cursor.
restart_subshell
Pass required id and optional prompt. Returns { id, promptDelivered }.
Restart stops the existing process tree and relaunches the same session. Subshell types any supplied prompt once the new process is ready. Don't restart your own pane: doing so terminates the process making the call.
terminate_subshell
Pass { "id": "SUBSHELL_ID" }. Returns the operation's { ok } result. Stops the process, revokes its pane token, and keeps the session record. 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 session record and captured history. Deletion is owner-only.
read_subshell_log
Pass { "id": "SUBSHELL_ID" } for the tail, or add from_byte (a previous nextByte) and optional limit to read only what followed that raw byte offset. Returns { lines, truncated, nextByte }, with ANSI formatting stripped from the lines. Tail reads end nextByte at the end of the log, so a tail seeds a cursor loop. Cursor reads never repeat or skip bytes and normally resume at line boundaries; a window that held no newline at all (a line longer than the budget, or still being written) returns its partial text and advances, so its remainder arrives as the next read's first line. 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 }.
SSH subshells reject this tool with SSH_OWNER_INPUT_ONLY, including when the pane token belongs to their owner. Use the dashboard as that owner to type into an SSH terminal.
Text and Enter are ordered input operations, not an atomic transaction. If the pane has exited, the call returns SUBSHELL_NOT_RUNNING. Restart it before retrying when you're authorized to do so.
transfer_files
| Argument | Requirement | Meaning |
|---|---|---|
from | Required object | { node, path }: source node (ID or unambiguous name from list_nodes) and absolute source directory on it. |
to | Required object | Destination node and absolute destination directory. |
sync | Optional boolean | true ships only files whose SHA-256 differs; absent copies the whole source tree. |
Returns { sync, archiveBytes, files, bytes, changed }. Subshell sends the directory tree through the server as one streamed archive. Neither machine needs tar or rsync.
Both endpoints must be enrolled nodes you own, online, and out of maintenance. You can't transfer files to or from the server host or browser. Each node's allowed-directory list limits which paths you can use; an empty list allows any path.
The transfer overwrites matching destination files without deleting other files. Running sync again after a completed transfer copies nothing unless files have changed.
The call waits for the transfer to finish and allows up to 4 GiB of uncompressed data per archive. An interrupted transfer leaves no partial destination tree. Run the transfer again to retry.
If an error says update the node, ask a human to update that endpoint's Subshell daemon. If your own call fails because its pane token lacks this feature's permissions, ask a human to restart the pane. Don't restart your own pane.
exec_in_terminal
Pass subshell_id and command, with optional timeout_ms in whole milliseconds. The default timeout is 30,000 ms; values outside 1,000–300,000 ms are adjusted to the nearest limit.
Returns { status, exitCode, output, truncated, nextByte }. When status is completed, exitCode contains the command's shell exit status. When it's timed_out, exitCode is null and the command keeps running.
You need a running, idle pane owned by the pane token’s user and using a plain terminal harness. SSH subshells reject this tool with SSH_OWNER_INPUT_ONLY. If the pane isn't ready, the tool types nothing and returns one of these errors:
SUBSHELL_NOT_RUNNING: restart the pane when authorized.EXEC_TERMINAL_ONLY: choose a terminal pane rather than an agent pane.EXEC_IN_FLIGHT: wait for the command already using this pane.EXEC_PANE_BUSY: read its output or wait, then retry.
A timed_out response returns the output collected so far and sends no further input. The output may end mid-line and includes the shell's echo of your command. It contains the most recent output up to 256 KiB; truncated tells you whether older output was omitted.
nextByte points just past the completion marker, or to where reading stopped. Pass it as from_byte to read_subshell_log to continue reading.
The completion marker uses POSIX $?, so a fish shell returns timed_out even after the command finishes. For interactive programs such as editors or password prompts, use send_to_subshell and read_subshell_log. See Terminal sessions.
list_channels
Arguments: {}. Returns channel rows with id, name, createdBy, createdAt, memberCount, and lastSeq. Discovery doesn't 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 doesn't 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
| Argument | Default | Meaning |
|---|---|---|
name | Required | Channel name. |
since | Stored read cursor | Nonnegative sequence after which to read. |
wait_seconds | 0 | Integer long-poll duration, up to 600 seconds. |
limit | 100 | Integer page size from 1 to 500. |
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 isn't.
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.
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 your updated prompt. It can't modify another user's prompt.
delete_prompt
Pass { "id": "PROMPT_ID" }. Returns { ok: true }. Permanently deletes an owned prompt; there is no undo.
Errors
A 401 means authentication failed. A 403 means your credentials don't allow the action. A 404 can mean the resource belongs to someone else, even if it appears in a list. A 409 can mean the process is unavailable or another operation conflicts with the request.
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.
Edit on GitHubLast updated on
