MCP tools

alto mcp serves 9 tools over the Model Context Protocol, on standard input and output. Add it to Claude Code with claude mcp add alto -- alto mcp. Each tool acts on the work pane linked to the conversation unless told otherwise (session, device, or use). See The MCP server for setup. Generated from alto 0.0.1.

run

Run a shell command in a terminal the person can see (their work pane, by default), typed at its prompt, and get back only the command's output and exit status as JSON: {output, exit, truncated, took, timed_out}. Refused, saying why, if something else is running there or someone has typed at the prompt.

Argument	Type	What it is
command required	string	The command, as you'd type it at the shell's prompt.
timeout	number	Seconds to wait for it; it keeps running past them (then `wait`). Default: until it ends.
max_lines	integer	Keep only the last this many lines of output (default 2000).
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

wait

Wait until the terminal's program reaches a state (idle, working, needs-you, done; or prompt: the shell back at its prompt), or prints text matching a regular expression. Default: until the prompt.

Argument	Type	What it is
until	prompt | idle | working | needs-you | done
text	string	A regular expression to wait for in what it prints from now on.
timeout	number	Seconds to wait at most.
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

read_screen

What the terminal shows now, as text, with where the cursor is: for full-screen programs (an editor, less, top). With `last`, the last lines of its scrollback instead.

Argument	Type	What it is
last	integer	The last this many lines, scrollback included.
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

send_keys

Type into the terminal: text, then keys by name (Enter, Escape, Tab, Up, PageDown, F5, q; with C-, M- or S- before it: C-c, M-x, S-Tab). For answering a program; for shell commands, use run.

Argument	Type	What it is
text	string
keys	array
force	boolean	Type even while an agent there shows a permission prompt or a question (refused otherwise, since letters pick its options). C-c and Escape alone always go.
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

describe

What a session is and what it can be asked to do, as JSON: its kind (agent, shell or job), its state (and what it's asking, if anything), and its methods, each with what it takes and gives (JSON Schema). Beyond the built-in ones (send, capture, wait, run, pause, resume, kill), a program in the session may offer its own, and an agent asking a question offers `answer`.

Argument	Type	What it is
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

call

Ask a session to do one thing, by a method `describe` lists, with its arguments as an object. Gives back {"ok": …} or {"error": {"code", "message"}}; the arguments are checked first, so a refused call changes nothing.

Argument	Type	What it is
method required	string	The method's name, from describe.
args	object	Its arguments, as its `takes` says.
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.

work

The work panes linked to this conversation: terminals beside it, here or on other devices, where the other tools act by default.

No arguments.

list_sessions

The sessions on this device, or on another (`device`), with what each is doing.

Argument	Type	What it is
device	string

use

Act on this session (on `device`, if given) from now on in this conversation, instead of the work pane; or start one there with new: true, or with new: true and `in`, on the least busy device that fits. With nothing, back to the work pane.

Argument	Type	What it is
new	boolean	Start a new session (a shell, or `command`) and use it.
command	string	With new: what it runs, in place of the login shell.
in	string	With new, instead of device: somewhere that fits, all of `os:windows`, `os:linux`, `os:macos`, `has:claude`, `has:docker`, `tag:NAME`, `gpu`, `pool:NAME` or a device's name (`alto devices` says what each has).
session	string	A session's id (from list_sessions). Leave out for the work pane linked to this conversation, or what `use` chose.
device	string	The device the session is on, by name (as `alto --on` takes it). Leave out for this one.