Using it from an agent (MCP)

Note

MCP is the second way to use this. The first is the agent skill — an agent that already has a shell needs nothing running to use aos, and that path works over SSH into any machine. Reach for MCP when your agent wants typed tools rather than a terminal.

$ aos serve mcp
aos mcp  http://127.0.0.1:14320/mcp
token    9c23b0efb0a002fe536a579adfd7cdb1

claude mcp add --transport http aos http://127.0.0.1:14320/mcp \
  --header "Authorization: Bearer 9c23b0efb0a002fe536a579adfd7cdb1"

Every non-hidden, non-blocking command available on this machine becomes one MCP tool, carrying the same summary, usage and examples the CLI documents.

The token is not optional

Loopback is not a permission. Every process on the machine can reach 127.0.0.1, and this surface drives windows, input and the filesystem — so a server that trusted loopback alone would be an open door for anything already running as you.

serve mcp mints a random token per run and refuses any request without it, either as an Authorization: Bearer header or a ?t= query parameter, compared in constant time. Pin one so a client configured once survives a restart:

export AOS_MCP_TOKEN=$(openssl rand -hex 16)   # or --token=…
aos serve mcp

A pinned token must be at least 16 characters; a shorter one is refused rather than quietly accepted.

Preview the catalogue first

$ aos serve tools
adapters_example             Print a starter adapter, ready to save and edit
adapters_list                List the adapters this machine has loaded
audio_volume                 Print the output volume, or set it
capture_screenshot           Take a screenshot
clipboard_paste              Print the clipboard to stdout
display_list                 List attached monitors with geometry and focus state
exec_capture                 Run a command and print stdout, stderr, and exit code as JSON
file_read                    Print a file, optionally a line range
window_move                  Move a window to a zone, a split, or coordinates

The tool name is the route with underscores. window move is window_move; aos window move Chrome --zone=1B and a window_move call with {"app":"Chrome","zone":"1B"} do the same work, through the same Runner. There is no second implementation behind the protocol.

Give an agent less than everything

aos serve mcp --groups=window,capture,exec   # a subset
aos serve mcp --gui=off                      # only the screenless tools

--gui defaults to auto: GUI tools appear only when the machine actually has a display. Offering an agent a tool that cannot run is worse than not offering it — it will try, fail, and try again.

It binds loopback

Serving this registry is remote control of the machine, so reaching it from elsewhere should be deliberate: an SSH tunnel, or an explicit --addr. The token travels in clear text, so --addr on an untrusted network wants a tunnel or a TLS front anyway — the tunnel is the better habit.

Keeping it running

A server an agent connects to should not depend on a terminal staying open:

aos service create mcp --autostart --now -- aos serve mcp
aos service status mcp     # exits non-zero unless it is running
aos service list
aos service remove mcp

A launchd user agent on macOS, a systemd --user unit on Linux, a Scheduled Task on Windows — per-user throughout, so nothing here asks for admin or sudo.

The protocol layer is not hand-rolled

MCP serving is toolnexus’s Toolkit.Serve, so the protocol work is conformance-tested rather than reimplemented here. Windows, monitors, input and screenshots come from windowctl. aos is the front door.

What an agent should read

aos skill install

writes the agent skill bundled inside the binary to ~/.claude/skills/ and ~/.agents/skills/. Because it ships in the binary, the instructions an agent reads cannot describe a different version than the one installed.

This site also publishes /aos/llms.txt and llms-full.txt, which is the same documentation in the form an agent prefers to read it.