MCP Server

Tools reference

The MCP server exposes a focused toolset over the businessdev.ALbuild module. Read-only tools are synchronous; mutating / long-running tools are asynchronous: they return a jobId you poll with get-job.

Tools

Tool	Tier	Notes
`list-containers`	read-only	Docker state + pool metadata.
`inspect-container`	read-only	Container detail + installed apps.
`find-artifact`	read-only	Resolve a BC artifact URL for a country/version/type.
`get-build-order`	read-only	Multi-project dependency build order.
`resolve-dependencies-plan`	read-only	Dry-run dependency resolution (what would be fetched).
`ensure-container`	mutating (job)	Warm-reuse or provision a container; optional dependency install + license.
`restart-container`	mutating (job)	Restart a container.
`remove-container`	destructive	Self-created → runs; shared/pre-existing → `approval_required`.
`reconcile-dependencies`	read-only	Manifest vs container vs feeds → satisfied / available-from-feed / missing.
`publish-app`	mutating (job)	Upload a built `.app` (base64) and publish it, the remote file transport.
`unpublish-app`	mutating (job)	Uninstall (`-Force`) + unpublish one or more apps by name, makes a re-publish at the same version idempotent.
`deploy-and-test`	mutating (job)	`appFolder` (local) or `apps` (base64 uploads) → publish clean → run tests.
`run-tests`	mutating (job)	Re-run tests without redeploy, the fast inner-inner loop.
`build-app`	mutating (job)	Compile the workspace fresh (fresh symbols → `alc`). Always runs on the host.
`install-dependencies`	mutating (job)	Resolve and install an app's dependency closure into a container.
`diagnose-app`	read-only	A container's actual app state: published versions, install/sync state, tenant data version, event-log tail, and named blockers with remedies.
`get-test-results`	read-only	Fetch the last test run's results.
`convert-coverage`	read-only	Raw BC coverage (`.dat`) → ALbuild JSON / Cobertura / Markdown.
`coverage-summary`	read-only	Summarise a coverage report.
`coverage-threshold`	read-only	Gate on coverage; reports below-threshold as a failure.
`coverage-delta`	read-only	Patch coverage of git-changed lines against a baseline ref.
`coverage-merge`	read-only	Merge coverage from several runs into one report.
`test-quality`	read-only	Assess AL test quality (assertions / empty tests / score).
`get-job` / `cancel-job`	read-only	Async job control.

The async job model

Anything that mutates a container or runs long returns immediately with a jobId:

Call the tool → get { jobId }.
Poll get-job { jobId } → state (running / succeeded / failed / cancelled), the streamed log, and on success the structured result (e.g. tests: { passed, failed, skipped, failures[] }).
cancel-job aborts a running job.

Remote app and dependency flow

When the agent is not on the MCP host (e.g. OpenClaw or Claude Code on a Mac talking to a Windows host), a filesystem path is meaningless on the host, so apps and feed credentials travel in the call:

reconcile-dependencies: send the app.json dependencies and the merged (app + workspace) albuild.json feeds, because the host can't read your repo. A private feed carries its API key in feeds[].token, the host doesn't have your credentials, so the agent supplies them (kept out of logs, passed to PowerShell via a child env var). You get back what's satisfied (already in the container, including Microsoft apps), availableFromFeed, and missing.
publish-app / deploy-and-test (upload form), send the missing .app files (and your app + test app) as base64, in dependency order; the server stages them on the host and publishes. Tests run by testExtensionId.

Local agents are simpler

When the agent runs on the MCP host, deploy-and-test takes an appFolder host path instead, it resolves the dependency closure from your feeds and publishes every .app in the folder directly.

Per-agent tool scoping

Each agent, identified by the stdio ALBUILD_MCP_AGENT value or its HTTP bearer token, sees only its allowed tools. This is a correctness requirement for small local models (fewer, relevant tools = better tool selection). Example roles: a coding-loop agent (full deploy/test), an ops agent (container hygiene), an architecture/DevOps agent (read-only visibility). The full toolset is available to claude-code.

Governance

Mutating tools run as logged async jobs: every action is traceable.
remove-container protects shared resources: a container the agent did not create this session returns { status: "approval_required" } instead of acting, for a human (or the OpenClaw Escalation Router) to approve. Only self-created containers are auto-removable (toggle with ALBUILD_ALLOW_SELF_CLEANUP).
Secrets stay where they belong: the host's own credentials (its PAT, signing cert) live on the host as the service identity. Per-feed API keys, which the host does not have, are supplied by the agent via reconcile-dependencies feeds[].token, kept out of logs and passed to PowerShell through a child env var (never inline). This relies on the authenticated, LAN/Tailscale-only channel.

Configuration (environment variables)

Variable	Default	Purpose
`ALBUILD_MODULE_PATH`	installed module	Path to the `businessdev.ALbuild` module to import.
`ALBUILD_POWERSHELL`	`pwsh`	PowerShell executable (falls back to `powershell`).
`ALBUILD_DOCKER`	`docker`	Docker executable.
`ALBUILD_MAX_WARM_CONTAINERS`	`2`	Warm-pool size cap (LRU eviction beyond it). RAM-bound.
`ALBUILD_CONTAINER_MEMORY`	`8G`	Memory per container; ceiling for a tool's `memoryLimit` request.
`ALBUILD_DEFAULT_ARTIFACT_TYPE`	`Sandbox`	Fallback artifact type.
`ALBUILD_ALLOW_SELF_CLEANUP`	`true`	Agent may remove containers it created without approval.
`ALBUILD_POOL_STATE`	`%LOCALAPPDATA%/albuild-mcp/pool.json`	Pool registry file.
`ALBUILD_MCP_HTTP_HOST`	`127.0.0.1`	HTTP bind host.
`ALBUILD_MCP_PORT`	`5020`	HTTP port.
`ALBUILD_MCP_TOKENS`	(none)	JSON `{ "<token>": "<agentId>" }` for HTTP bearer auth.
`ALBUILD_MCP_AGENT`	`claude-code`	Agent identity for the stdio transport (scopes the toolset).
`ALBUILD_MCP_SKIP_PREFLIGHT`	(unset)	Set to `1` to bypass the start-up preflight gate.

See the step-by-step guide to wire the server into VS Code, Claude Code, or a remote host.

Last modified on August 22, 2026

Get Started