Five tools for managing your toolchain.
MCP AIDC gives your agent five tools: one reads the state of your toolchain and four change it. Each returns the outcome of the requested AIDC operation.
Every tool accepts projectDir, an existing absolute directory (it defaults to the server's own); it selects which project's declarations apply and operations can affect shared installations.
Read what is installed and selected.
| Tool | Use it to | Parameters |
|---|---|---|
aidc_query | Read the current tool selection, installed or available versions, where tools live, plugins, the hub status (the hub is the MAIT service that supplies packaged tool versions) or a diagnostic report. It requests no tool installation or activation. Use it before changes; diagnostic actions can also refresh cached observations. | action (required), tool, executable, version, pattern, available, allSources, detailed, projectDir |
The actions of aidc_query:
| Action | Needs | Use it to |
|---|---|---|
current | none | Read the current selection, optionally for one tool |
list | none | List installed or available versions; pattern filters, available asks the packaged sources (the hub and local packages), allSources adds the vendors' catalogs |
latest | tool | Resolve the newest matching version |
describe | tool | Read a tool's metadata and installed versions |
locate | tool or executable | Find an installation, or the tool an executable belongs to |
plugins | none | List the plugins |
hub | none | Check the hub status and connection |
doctor | none | Run the diagnostic report; detailed adds more |
Why: read first. Always send tool together with pattern. For locate, give exactly one of tool or executable, and do not send version with executable.
Install tools and choose their versions.
| Tool | Use it to | Parameters |
|---|---|---|
aidc_install | Install one tool, or set up every tool a project declares. It runs immediately with no preview or confirmation, so look at the state first. | action (required: tool or project), tool, version, projectDir |
aidc_activate | Choose which version of a tool a project, your account or only the current session uses. It takes effect immediately. | tool (required), version (required), scope (project, the default, home or session), projectDir |
Why: one call per decision. project setup needs an absolute projectDir, reads its .aidc.yaml and installs the active declared version of each ordinary tool; after project setup, confirm each required tool with aidc_query list. Project scope writes .aidc.yaml, home scope persists your own selection, and session scope follows the AIDC shell session and does not change your client's environment. Use only the three documented scope values.
Preview upgrades and confirm removals.
| Tool | Use it to | Parameters |
|---|---|---|
aidc_upgrade | Upgrade one tool, or every tool a project declares. By default you only get a preview of what would change; nothing is upgraded until you ask to apply it. | tool or all (exactly one), version, keep, noMigrate, apply (booleans, default false), projectDir |
aidc_remove | Uninstall tool versions, or clean out older eligible versions after checking other projects. Without confirmation an uninstall only returns a reminder and a clean-out is a dry run, so nothing is deleted by accident. | action (required: uninstall or prune), tool, version, all, confirm (default false), projectDir |
Why: the dangerous steps have a gate. Applying an upgrade can install, migrate, activate and remove according to its flags. Apply the exact version you reviewed. With all: true an upgrade skips missing or unsupported tools and system packages ; afterwards, confirm each target with aidc_query list. For removal, give a tool with no version to remove all its versions, and never combine all with tool or version. For prune, omit version and all. It protects versions according to the current AIDC context, so check other projects before you confirm.
One built-in reminder.
aidc_manual takes no arguments and returns a short usage message: discovery, project context, the preview defaults, confirmation and the output limits. It is not an approval and does not replace this page.
What a call returns and what it cannot.
A completed command comes back as text holding JSON with command, exitCode, stdout, stderr and truncated. Read isError first, then that text; there is no top-level success or data.
| Limit | Value |
|---|---|
| One call | One AIDC command, with a 15-minute wait |
| Output | The first 16 KiB of each of the output and error streams, with truncated: true when it was longer |
| Account | Every command runs as the account that started the server |
| Settings | --aidc-binary only; there is no configuration file |
An argument rejected before AIDC runs comes back as an invalid-parameters error. An AIDC command that fails keeps its full envelope with isError: true, and a failure does not undo earlier effects, so check the installed versions before you repeat a change. See Troubleshooting.