Copy page

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:

1. Call the tool → get { jobId }.
2. 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[] }).
3. 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:

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

---

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.