Agent tools

What agents can do over MCP. Tokens and sign-ins that may only look get the first group.

Looking

Tool	What it does
whoami	The organization, what the agent may do, and its limits.
list_projects	Projects (and previews) it may see.
list_services	A project's services with state and address.
get_service	Everything about a service; secret names only, never values.
get_project_file	A project written out as alf.toml, for push_code to deploy once changed.
list_deployments / get_deployment	Deployments, with the end of the build log.
wait_for_deployment	Waits until a deployment is live or failed (or a candidate is ready), with why it failed and the app's last output.
get_logs	The container's recent output.
get_metrics	Requests, errors, response time, wake-ups, data; memory the app holds, and the newest minute it was awake.
list_servers	Where services run or can run: each server's region, whether it takes new services right now, and which services are on it.
list_previews	A project's previews.
list_snapshots	A volume's snapshots and its schedule.
get_approval	Whether a change waiting for approval was decided.
check_domain	A custom domain's status and DNS.
list_templates	The one-click deploys: what each creates and asks for.
list_buckets	A project's buckets: S3 endpoint, name, key id, what each holds.
list_ports	A service's public TCP and UDP ports: address, who may connect, who was turned away.
check_port	Whether a public TCP port can be reached from outside.
list_alerts	The alert rules, and which are firing right now.
list_notification_channels	Where the organization is told things, and which events each channel listens for. Addresses are shown in part only.
get_error_page	The organization's own error page, if it has one.
get_activity	What was changed lately, by people and by agents: who, what, when, and whether it worked.
get_billing	Where the organization stands with billing, this month so far and where it's heading.
get_usage	A month's container hours, requests and data, per day and per service.
list_promotions	What was promoted into an environment.
get_session_commands	Every command run in a session, with its exit code.

A token limited to one project gets that project's activity and usage, and only its services in list_servers. get_billing is about the whole organization, so it doesn't get that.

Changing (read & deploy)

Tool	What it does
create_project	A new project.
create_service	A service running an image, or one that waits for code.
add_database	Postgres, MySQL or Redis in a project, backed up and private. See databases.
create_bucket / connect_bucket / rotate_bucket_key	S3 storage for an app's files, given to an app by reference. The key's secret is never handed to the agent. See buckets.
connect_database	Gives an app a database's URL, as a reference, and deploys it.
update_service	Settings (image, Dockerfile, port, scaling, …).
set_variables	Add, change or remove variables and secrets; deploys them unless told to wait.
deploy	Deploys now.
rollback	Back to the last version that ran (or a given one).
upload_code	A one-time link and command that deploys the working directory to one service; says what happens to staged variables; can hold the new version as a candidate.
promote_candidate	Makes a healthy candidate the live version.
discard_candidate	Removes a candidate; the live version was never touched.
exec	One command in a container (migrations and the like); with session_id, in a container that's kept. Needs "may run commands".
open_session	A container to work in, so one command sees what the last one left. Needs "may run commands".
list_sessions	What's open on a service.
close_session	Ends one and removes its container.
push_code	A one-time link and command that deploys the working directory to a project: every service of its docker-compose file, or its Dockerfile as one service. Creates what's missing.
create_preview / extend_preview / end_preview	Preview environments.
create_snapshot / restore_snapshot	A backup of a volume before a risky change, and putting one back.
add_domain	A custom domain (you create the DNS record).
deploy_template	Deploys a one-click deploy into a project, as one group.
open_port	A public TCP or UDP port for a database or other non-HTTP service, open to the addresses given.
close_port	Closes a public port.
list_groups / create_group / update_group / delete_group	Groups on a project's canvas: which services, computers and buckets belong together. Removing a group leaves what was in it as it is.
update_project	Renames a project, or changes the part of its addresses that names it. Whether agents need approval there stays a person's to set.
discard_staged_variables	Throws away variable changes that were waiting for a deploy.
add_volume	A volume for a service that exists already.
set_snapshot_schedule	Snapshots of a volume by themselves: how often, how many are kept, and whether each gets a copy off the server.
copy_snapshot_offsite	A copy of a finished snapshot off its server.
update_port	Who may connect to a public port, without closing it: its address stays the same.
watch_service	The usual three alerts for a service, or for all of them, in one go.
create_alert / update_alert / delete_alert	An alert rule: what it watches, its threshold and window, on or off.
add_notification_channel / test_notification_channel / remove_notification_channel	Somewhere the organization is told things: Slack, Discord, a webhook or email.
set_error_page / remove_error_page	The organization's own error page.

Notification channels, the error page and an alert on every service belong to the whole organization: a token limited to one project can't change them. It can still make alerts for its own project's services.

Deleting

Only for a token or sign-in that was given May delete (see Keeping agents safe):

Tool	What it deletes
delete_service	A service, with its volumes' data, snapshots, domains and ports.
delete_bucket	A bucket and every file in it.
delete_volume	A volume's data and its snapshots.
delete_snapshot	A snapshot, and its copy off the server.
remove_domain	A custom domain from a service.
delete_project	A whole project. The agent has to give the project's name to confirm.

Without that permission an agent can still end previews, close ports and remove groups: none of those lose data.