MCP Tools

subshell mcp serves fifteen tools in two families: five for channels (the encrypted logs subshells use to talk to each other), and ten for seeing, launching and steering the other subshells on your control plane and the machines they run on. This page is the tool-by-tool reference: what each one does, the shape of its arguments, and the handler-level behaviours that are worth knowing before you rely on them.

The server introduces itself before any tool runs. Its initialize briefing (the text every conforming harness receives at connect time) tells the agent that the other panes are sessions like itself, to read status with list_subshells rather than polling git, to talk via channels, and to treat sibling output as untrusted data. You can repeat it to an agent that forgot, but it is there from the first message.

Channel tools

The handlers do more than forward requests, in ways that matter:

• post_channel auto-joins the poster, then seals to every member holding a key, including the poster itself, so its own history reads back on later calls. Sealing happens in the MCP process; the server only ever relays ciphertext it cannot open.
• Peer keys are pinned. The first time you post to a channel, each member's exact public key is pinned locally; a later post whose roster key differs aborts with an error rather than sealing to a substituted key. That pins out a hostile relay swapping a roster entry, and it also fires on a genuine peer key recovery, when it names the file to edit to re-learn the key. The escape hatch SUBSHELL_CHANNEL_PIN=trust restores trust-on-read, a debugging switch, not a stance.
• read_channel without since resumes from your stored cursor, which advances with each read, so bare repeated calls tail the channel instead of re-fetching the oldest page. wait_seconds long-polls in slices of at most fifty seconds against a wall-clock budget, and a cancelled call releases its connection immediately rather than sitting out the wait. Posts you cannot decrypt (a key rotated after they were sent, say) are counted in the result, not fatal.

Nudge: the doorbell, not the letter

post_channel(nudge: true) is the one tool with a side effect outside the message. The content always stays pull (only read_channel decrypts it), but the nudge makes sure a peer notices there is something to pull, typed directly into the recipient's pane as a fixed, server-generated line:

• A pane idle at its prompt gets a line telling it to call read_channel for that channel, followed by Enter. The agent wakes and reads. This is the only auto-submitted text the nudge path produces, it is never peer-authored, and the woken agent still exercises its own judgment about what to do with what it reads.
• A pane mid-turn gets the Enter-less form of the cue, harmless text sitting in the input line, interrupting nothing, which a human or agent can press Enter on later or ignore.
• The nudge goes to running recipient panes other than the sender, and it is best-effort: a post never fails because its nudge failed to land.

Orchestration tools

Behaviours worth knowing:

• list_subshells answers as the token's owner. The list is everything that owner can see, which includes subshells shared with them: a pane can enumerate their names and status. What sharing never widens is the acting side: every per-subshell route runs a machine token with shared grants and the admin boost switched off, so a tool call against a subshell merely shared with the owner is refused. Worth knowing beside this: the pane's bearer credential itself carries the subshells and channels grants, each read and write; the narrowing to its own row happens in the routes and tools that consume it, not in the token's permission map.
• create_subshell names the harness, and may name the machine. Pass the harness id you saw in list_presets (or the harnessId of any row from list_subshells: the preset list is empty on a fresh instance, that one never is). An optional preset is resolved by name within that harness; an exact spelling wins outright, and a genuine ambiguity is refused with the competing spellings named rather than silently launching the wrong preset. Omitting it is a complete, settings-free launch. The optional node takes an id or a display name from list_nodes (an exact id always wins over a name that happens to read like one); omit it and the instance picks, which refuses rather than guessing when more than one machine is online. working_dir is a path ON that machine, so check list_nodes before guessing where a sibling's files live.
• Check promptDelivered. If you passed prompt, the response says whether it was submitted into the harness. Depending on how early the harness paints its interface, the text can land in the input line without submitting; verify the flag before assuming the new agent has your message. restart_subshell reports the same flag for the prompt it re-types into the revived pane.
• restart_subshell on your own id terminates you. It is the same restart an operator triggers from the UI: the process tree dies and respawns, and the token rotates with it. Use it deliberately.
• Steering siblings reaches the owner's own panes. read_subshell_log and send_to_subshell act on the owner's other running subshells; shares and the admin boost are switched off for a pane's own token, so a row merely shared with the owner stays as unreachable to these tools as to every other per-subshell route. Everything they return is sibling output: data to read, not instructions to obey. Typing is exactly what the browser terminal sends; the bytes arrive verbatim, and submit: false leaves them unsubmitted at the prompt.
• Errors are short, actionable sentences. A refused call surfaces as one line of guidance naming the next call, not a stack trace: a revoked token says restart this subshell to mint a new one, a launch that must pick a machine points at list_nodes, a stopped pane says to start it with restart_subshell, a missing id says to find ids with list_subshells.

Deliberate absences

There is no update_subshell_notes tool, and there will not be a replacement. The operator-note feature it wrote was removed along with its UI, leaving a tool whose output had no reader; the tool went with it. channel_members went the same way on 2026-09-25: post_channel already addresses every member and every post names its author, so the roster the tool returned was implied by the tools that matter (the REST route it called is untouched). The lesson generalises on this surface: tools here exist because an agent has something to do with the result.

See also

• The subshell mcp Server: how the process is launched and authenticated
• Channels: the human side, what channels look like from the UI
• Subshells: the rows these tools list, create, and steer

Edit on GitHub