25 tools, all written for MAIT.
MCP Apt gives your agent 25 tools for looking up, changing and inspecting packages. It is not a wrapper around the system package manager. Six further tools in the tool list are not supported; the tool reference names them and what to use instead.
A tool result is JSON in a text item; check isError, and remember that isError: false does not prove a package change completed.
Required values are strings or arrays of strings, and optional booleans default only when absent; wrong types, nulls, empty required lists and unknown properties/actions fail validation. Many tools accept name:architecture; for multi-architecture installs, test on a recoverable environment first. File arguments are paths on the server, not your computer.
Look up packages without changing them.
| Tool | Use it to | Parameters |
|---|---|---|
apt_update | Refresh the package information from the configured repositories. It reports success even when one source failed, so read the details; you can also skip all work. | no_cache_update (default false) |
apt_search | Find packages whose name contains a piece of text. It matches names only, not patterns or descriptions. | pattern (required) |
apt_show | Read a candidate package's details and dependency information. If a requested package has no candidate, the whole call fails. | packages (required, array) |
apt_list | List recorded packages with version, architecture and status, optionally only installed ones or those matching a pattern. | installed, pattern |
apt_policy | Read a package's installed and candidate versions. Read the installed and candidate versions. | package (required) |
apt_depends | Read a package's dependency clauses as written. They are not a worked-out install plan. | package (required) |
apt_rdepends | Find which packages depend on a given one. This comes from stored dependency data, so it can be incomplete and matches names literally. | package (required) |
apt_search_file | Find the package that owns an exact file path, from recorded ownership. It is not a search across the repositories. | path (required) |
apt_list_files | List the files a recorded package owns, from its records; the file system is not scanned. | package (required) |
Why: cached queries make no repository request, so they are the safe place to start; opening the package information can still create directories, cache aliases or lock files. A catalogue result does not prove a repository was fully refreshed or that package content was authentic.
Add packages and move them forward.
| Tool | Use it to | Parameters |
|---|---|---|
apt_install | Install packages. It runs without asking and has no dry run, so call it only when the task is authorized to change the system. | packages (required, array), no_recommends, download_only, yes (booleans, default false) |
apt_reinstall | Install the same packages again. It can pick a newer version than the installed one, and it can report a half-configured package as reinstalled. | packages (required), yes |
apt_configure_pending | Retry every half-configured package on the system, not only the one from your last request. Use it to finish an interrupted install. | none |
apt_upgrade | Upgrade installed packages, with only limited control over which ones. | yes |
apt_full_upgrade | Upgrade packages and allow the additions and removals it identifies as needed. It does not guarantee a complete distribution upgrade. | yes |
Why: an outcome with installed, errors, warnings, requested and removed_for_conflicts says what changed. yes is read but controls no prompt, because these run noninteractively. An unresolved dependency clause can be skipped, a failing post-install script can leave a package HalfConfigured while it appears in the outcome, and an upgrade can leave the recorded version behind the extracted archive's. Verify both the state and the capability you needed. download_only is not a preview: conflicting packages are removed before it returns.
Take packages and caches away.
| Tool | Use it to | Parameters |
|---|---|---|
apt_remove | Attempt removal while retaining configuration identified in package records; verify what stayed. The result can omit failures of the removal scripts, so check the state afterwards. | packages (required), yes |
apt_purge | Remove packages together with their configuration files. A failure can leave the package in a partial state. | packages (required), yes |
apt_clean | Free disk space by deleting the whole download cache and recreating its empty folder. | none |
Why: there is no plan and no rollback after a failure; inspect the final state and the diagnostics. Packages marked required are protected from removal; your environment owner can change this.
Read a package file or fetch its source.
| Tool | Use it to | Parameters |
|---|---|---|
apt_info | Read the control information of a package file on disk, to see what it is. | file (required) |
apt_contents | List the paths inside a package file without unpacking it. | file (required) |
apt_source | Fetch a package's source code and unpack it into a folder. It needs a source repository to be configured. | package (required), output_dir (default .), extract (default true) |
Why: inspect before you trust. MCP Apt authenticates the source index, checks every file’s SHA256 and exact size, and refuses an existing extracted source directory. Give it a new owned directory. After a failure, files or a half-unpacked tree can remain, and a missing extracted_to means unpacking did not complete.
Read package state and set marks.
| Tool | Use it to | Parameters |
|---|---|---|
apt_status | Read a package's record: version, architecture, state (such as installed, half-configured or only configuration files left) and why it was installed. | package (required) |
apt_mark | Mark a package as installed automatically or by choice. | package (required), mark_type (required: auto or manual) |
apt_mark_show | List packages by mark or selection, such as automatic, manual, held or chosen for removal. An unrecognised action is rejected. | action (required: showauto, showmanual, showhold, showinstall, showremove or showpurge), packages (optional glob filters) |
apt_hold | Record a hold on a known package for the supported upgrade path. | package (required) |
apt_unhold | Clear a hold and set the package's selection back to install. | package (required) |
Why: read the record before you change it. Holds protect the supported upgrade path and some explicit installs, not every route: a dependency-driven install can still move a held package. apt_mark_show leaves out the architecture and can list a name twice.
What to expect when a call fails.
| Limit | Value |
|---|---|
| Call rate | Installation tools share 10 calls a minute, apt_upgrade has 5, apt_remove has 10, and the other apt_ tools share 60; the buckets are shared across clients and refill continuously |
| One call | Served wait budget 120 seconds including queued work; unfinished filesystem work can continue afterward without undoing effects |
| Parallel work | The server allows four active package jobs; a timed-out unfinished job retains its place until it ends |
| Request/result bytes | The server rejects arguments above 64 KiB and serialized results above 1 MiB; narrow the request instead of assuming a partial successful answer |
| Scripts | Each maintainer script defaults to 60 seconds, configurable within 1–60 seconds; child output is captured with explicit limits |
| Environment | Shared by every connection; session modes do not create a private copy |
Plan automated callers around these limits. Before you repeat a change after a failure or a timeout, wait for a diagnosed state of the environment. See Troubleshooting.