zas-agent MCP server exposes, in one page.
Commands
Tools
channel takes a channel name or a channel id. A name has to match exactly one granted channel. With exactly one grant, every tool that takes channel can leave it out except zas_list_items and zas_get_item, which always name theirs.
zas_status
Says whether this machine is paired, and lists the channels this agent may send to or read from. Also prints the package version, the profile, where the agent’s secrets are stored, the automatic-update setting with any release staged for the next launch, and the telemetry state. No arguments.
zas_pair
Pairs this machine with a Zas account. The first call returns a URL for you to open; a later call says whether you approved. In a profile that is already paired, approval replaces the old agent.
zas_send_file
Sends a file from this machine into a granted channel. Returns the item id, or a job id when the upload takes longer than a minute.
A channel in Directo mode refuses this tool with
direct_mode. Use zas_send_direct there.
The file is read, encrypted and uploaded in batches of 16 MiB, so a large file never sits in memory whole. If the file changes while it is read or uploaded, the send stops with file_changed and publishes nothing.
JPEG, PNG, WebP, GIF and TIFF images up to 80 MiB and 16 million pixels get a preview. Larger images and other formats, BMP included, are sent without one.
zas_send_note
Sends a note: plain text, or a code snippet with its language.
expires_in_days
Both sending tools take it, and it only ever shortens an item’s life. A request longer than the plan grants is answered with the plan’s number rather than refused, so asking for 100 days gives you five. The floor is one whole day, because the countdown ring counts whole days.
It is worth setting for output that is stale tomorrow: a build log, a test run, a screenshot of a fix.
zas_send_direct
Sends a file through Directo: a live, device-to-device transfer into a granted channel that is in Directo mode. Nothing is stored. Somebody has to press Receive on another device within ten minutes. The call waits a minute and then returns a job id to check with zas_jobs.
A channel that is not in Directo mode refuses this tool with
not_direct_mode.
zas_receive_direct
Receives a file sent through Directo, straight onto this machine. It waits for the offer, takes it, and writes the file to disk. Only for a channel in Directo mode, and only with a grant that includes reading, because it writes onto the machine.
It never overwrites an existing file. The wait for an offer alone can take ten minutes, so the call returns a job id after a minute.
zas_send_direct_fallback
After a zas_send_direct job failed in flight, delivers the same file through reliable delivery instead. Zas encrypts the file on this machine and stores only that encrypted copy for up to 24 hours; it uses none of your space, and the device that claimed the offer can download it later.
This stops being Directo: the encrypted bytes pass through storage. The tool’s own description tells the model to ask you first, because it is your choice, not the model’s.
zas_receive_direct_fallback
After a zas_receive_direct job failed in flight, downloads the encrypted copy the sender chose to store. It works only if the person sending picked reliable delivery for that transfer. The file is decrypted on this machine and written to the same destination.
zas_list_items
Lists the most recent items in a channel. Needs a grant that includes reading.
zas_get_item
Fetches one item. A note comes back as text; a file is written to disk.
It never overwrites an existing file. A name that is taken gets a suffix, and the path it answers with is the one it actually wrote.
zas_edit_item
Changes an item this agent sent, keeping its id: the title of a file or a note, or a note’s text, language and secret cover. Needs a grant that includes reading and sending.
Pass only the fields you are changing. Anything you leave out stays as it is.
It refuses an item sent by another agent or by a person, with
not_yours. On a file, only title can change: anything else answers not_a_note, and the bytes change with zas_replace_file.
zas_replace_file
Replaces the bytes of a file this agent sent with a file from this machine. The item keeps its id, its place in the channel and its pin. Returns the item id, or a job id when the upload takes longer than a minute.
It refuses an item this agent did not send with
not_yours, a note with not_a_file, and an item that has a public share with item_shared. The owner removes the share first.
It reads and uploads the new file the same way zas_send_file does: in 16 MiB batches, and refused with file_changed if the file changes during the transfer.
zas_jobs
Lists the sends and Directo transfers this server started, newest first, with the phase each one reached and how it ended. A job_id from a long send is redeemed here, and a finished job keeps its result.
Error codes
The agent answers in a closed set. Anything a route says that is not in this set collapses toupload_failed or network, so no raw server string ever reaches a terminal, and no stack trace does either.
Pairing and identity
Channels and grants
Sending and reading
Directo
Everything else
Files on disk
One directory per profile, so one machine can hold a Claude Code agent and a Codex agent without either reading the other’s keys.
One file sits a level up, in
~/.zas/agent/ itself, because it is a choice about the machine rather than about one identity:
Every file is written through a temporary file and renamed into place, so a crash mid-write cannot leave half a file behind.
Where the private keys live
Since 0.11.0 the private keys and pairing secrets are not kept in the JSON files. They live in the operating system’s secret store, and older files move there on the next start.
On macOS and Linux the agent refuses a secret file that another user owns, that is a link, or that the group or others can read.
zas_status says which store this profile uses.
A profile protected by the OS is not a portable backup. Do not copy it to another machine: pair a new profile there. Older agent versions cannot read migrated secrets, so keep 0.11.0 or newer installed.
Deleting the directory makes the machine forget the agent. It does not revoke it. That happens in Settings → Agents → Revoke. On macOS and Linux, Keychain or Secret Service entries can stay behind under the service
red.zas.agent; remove them with the OS credential manager.Automatic updates
Since 0.11.0 the agent keeps itself up to date. It is on by default for installations from npm. While it serves, the agent checks npm for the latest stable release, at most once a day. It installs a newer release in~/.zas/agent/.updates, checks that it reports the expected version, and uses it on the next launch. Restart your agent, or its MCP connection, to apply it. A running transfer is never restarted, and pairing and grants stay as they are. If the check fails or the machine is offline, the current version keeps working.
npx -y zas-agent@latest in place of zas-agent. ZAS_AGENT_AUTO_UPDATE=0 turns the updater off for the process, and 1 turns it on, whatever settings.json says.
To pin a version, put the exact version in the launch command, for example zas-agent@0.12.0, and turn updates off. A launch command with @latest still asks npm for the newest package.
Source checkouts and prerelease builds never update themselves.
Telemetry
The agent reports the pairing funnel and oneagent.tool_call event per tool call, so Zas can see which tools work and which fail. It is on by default and it prints a notice the first time.
Since 0.10.0, file sends, note sends, downloads and Directo transfers also report their progress: transfer.started, transfer.stage_started, transfer.slow after 30 seconds, transfer.phase_timing and transfer.finished. Each event carries the item category, the transport, byte counts, a size bucket, stage durations and the outcome, joined by a random ID for that attempt.
What it never sends: file names, titles, note bodies, channel names, paths, or item content.
A report never delays or fails a tool call. It is sent after the answer, tried once, and dropped if it fails. Nothing is reported before pairing.
Three ways to turn it off, in the order they are read:
zas-agent telemetry with no setting prints the current state and which of the three decided it. zas_status prints the same line.
Settings
Only
--profile, ZAS_AGENT_HOME, the telemetry switches and the update switch are worth setting by hand. The rest exist so the package can be pointed at a test deployment.
The agent checks every address it is given, saved ones included. It refuses plain HTTP to anything other than localhost, 127.0.0.1 or ::1 with unsafe_endpoint. It also never follows a redirect on a request that carries credentials.
Numbers
Where to go next
Connect an agent
Pairing, the harness commands and the failure modes.
Limits
Every limit Zas enforces, agents included.
FAQ
Short answers to the usual questions.
Recommendations
Safe practice, and the warning about secrets.