# 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](/docs/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](/docs/error-pages), 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](/docs/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](/docs/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](/docs/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](/docs/agent-safety)):

| 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.