Copy page

MCP Server

Get started with the MCP server

This guide takes you from nothing to an AI agent that provisions a Business Central container, publishes your app and runs its tests. Pick the setup that matches how you work:

• A, VS Code (Copilot agent mode): the ALbuild extension contributes the server for you. Easiest for AL developers.
• B, Claude Code: a small .mcp.json in your repo.
• C, Remote HTTP host: a shared Windows Server for Mac / Docker-less agents.

---

1. Prerequisites

Install the PowerShell module first and smoke-test it:

Code
Install-Module businessdev.ALbuild -Scope CurrentUser -Force
Import-Module businessdev.ALbuild   # should import without error

---

2. Verify the host is ready

Run the preflight before wiring up any client, it pinpoints PowerShell / module / Docker problems:

Code
npx -y @365businessdev/albuild-mcp --check

You want all green:

Code
[ OK ] PowerShell: pwsh 7.5.5
[ OK ] businessdev.ALbuild module: OK 2.31.0
[ OK ] Docker: Windows-container mode.
Result: READY.

The server runs this same preflight as a hard gate on start and refuses to launch if PowerShell or the module is missing (bypass with ALBUILD_MCP_SKIP_PREFLIGHT=1). Fix any [FAIL] line first.

---

A: VS Code (Copilot agent mode)

The ALbuild VS Code extension contributes the albuild MCP server natively, so there is no mcp.json to write.

1. Install/update the ALbuild extension (VS Code Marketplace). It requires VS Code 1.101+.
2. Open your AL project. The extension launches the server locally via npx and reuses its own albuild.powershell.executable / albuild.module.path settings.
3. Open Copilot Chat → Agent mode; the ALbuild tools appear in the MCP/tools list.

Relevant settings:

---

B: Claude Code

No server to keep running, the client launches it on demand. Add a .mcp.json to your repository (or run claude mcp add):

Code
{
  "mcpServers": {
    "albuild": {
      "command": "npx",
      "args": ["-y", "@365businessdev/albuild-mcp"],
      "env": { "ALBUILD_MCP_AGENT": "claude-code" }
    }
  }
}

Approve the project server when Claude Code prompts (or pre-approve it in .claude/settings.local.json with "enabledMcpjsonServers": ["albuild"]). MCP servers load at session start, if you add this to a running session, run /mcp to reconnect.

The same file works for Claude Desktop and Cursor.

---

C: Remote HTTP host (for Mac / OpenClaw agents)

Run the MCP on a dedicated Windows Server; remote agents connect over the LAN or Tailscale.

C1. Start the server

Code
npm install -g @365businessdev/albuild-mcp

# one bearer token per agent (the value scopes the toolset)
$env:ALBUILD_MCP_TOKENS    = '{"<token-linus>":"linus","<token-you>":"claude-code"}'
$env:ALBUILD_MCP_PORT      = '5020'          # OpenClaw reserves 5010-5099
$env:ALBUILD_MCP_HTTP_HOST = '127.0.0.1'     # LAN/Tailscale only
albuild-mcp --http

Run it as a service so it survives reboots (e.g. with NSSM, pointing at node …\@365businessdev\albuild-mcp\dist\index.js --http with the env vars set on the service).

C2. Point a remote agent at it

The endpoint is http://<server-host>:5020/mcp with an Authorization: Bearer <token> header:

Code
{
  "mcpServers": {
    "albuild": {
      "type": "http",
      "url": "http://<server-host>:5020/mcp",
      "headers": { "Authorization": "Bearer <token-you>" }
    }
  }
}

---

3. Tell the agent how to use it

Drop a workflow file into your repo so the assistant follows the right process (the package bundles a ready template at templates/ai/CLAUDE.md). The essential inner loop:

0. Ask the cheap question first. If what you need is "what does this AL return for these inputs?", albuild probe answers it locally in a fraction of a second, with no container. It is a CLI command rather than an MCP tool, so run it through the shell. Use the container loop below when the answer depends on the real platform, or to confirm the end state.
1. Compile the app(s) with the AL compiler, the MCP does not compile. Fix compile errors first.
2. ensure-container { country, bcVersion }, get a warm-reused or freshly provisioned BC container for the target. Poll get-job until done.
3. reconcile-dependencies: send the app.json dependencies and the merged albuild.json feeds (with any private-feed API keys); see what's satisfied / available / missing.
4. Provide the missing apps: publish-app (or the apps upload form of deploy-and-test) uploads the built .app bytes as base64, in dependency order.
5. deploy-and-test: publish clean and run the suite; read tests.failures[], fix the AL, recompile, and run-tests again.
6. Iterate until green, then hand off to CI: a local green is the inner loop, not a release.

See the Tools reference for every tool and the remote app/dependency flow.

---

Troubleshooting

• --check fails on the module: run Install-Module businessdev.ALbuild from step 1.
• Container tools error but read-only tools work: Docker isn't in Windows-container mode.
• VS Code shows no ALbuild tools: needs VS Code 1.101+; confirm albuild.mcp.enabled is true and reload the window.
• Claude Code says "no MCP": the session started before .mcp.json existed; run /mcp, or confirm the editor's working directory is the repo root.
• HTTP 401: missing/wrong bearer token. HTTP unreachable: check ALBUILD_MCP_HTTP_HOST, the firewall, and Tailscale.