import { Callout } from "zudoku/ui/Callout";

# 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)](#a--vs-code-copilot-agent-mode)**: the ALbuild extension contributes the server for you. Easiest for AL developers.
- **[B, Claude Code](#b--claude-code)**: a small `.mcp.json` in your repo.
- **[C, Remote HTTP host](#c--remote-http-host-for-mac--openclaw-agents)**: a shared Windows Server for Mac / Docker-less agents.

---

## 1. Prerequisites

| Requirement | Needed for | Get it |
| --- | --- | --- |
| **PowerShell 7+** (`pwsh`) | Runs the ALbuild module | https://aka.ms/powershell |
| **`businessdev.ALbuild` module** | The engine every tool calls | `Install-Module businessdev.ALbuild -Scope CurrentUser -Force` |
| **Node.js 20+** | Runs the MCP server | https://nodejs.org |
| **Docker Desktop** (Windows containers) | Container / deploy / test tools | https://www.docker.com → *Switch to Windows containers* |

<Callout type="info" title="Docker is only needed for container tools">
Read-only tools (`find-artifact`, `reconcile-dependencies`, dependency planning) work without Docker. The container / publish / test tools need a **Windows host with Docker in Windows-container mode**.
</Callout>

Install the PowerShell module first and smoke-test it:

```powershell
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:

```bash
npx -y @365businessdev/albuild-mcp --check
```

You want all green:

```
[ 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](../vscode-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.

<Callout type="info" title="On macOS / Linux">
BC container tools need Windows + Docker. On a Mac, set `albuild.mcp.http.url` to a shared remote host (see [C](#c--remote-http-host-for-mac--openclaw-agents)) and store its token with the command **ALbuild: Set MCP HTTP Token**.
</Callout>

Relevant settings:

| Setting | Default | Purpose |
| --- | --- | --- |
| `albuild.mcp.enabled` | `true` | Contribute the MCP server to VS Code. |
| `albuild.mcp.transport` | `auto` | `auto` (HTTP if a URL is set, else local stdio), `stdio`, or `http`. |
| `albuild.mcp.http.url` | _(empty)_ | Remote (Streamable HTTP) endpoint, e.g. for a Mac. |
| `albuild.mcp.agent` | `claude-code` | Agent identity sent to the server (scopes the toolset). |

---

## 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`):

```json
{
  "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

```powershell
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](https://nssm.cc), pointing at
`node …\@365businessdev\albuild-mcp\dist\index.js --http` with the env vars set on the service).

<Callout type="caution" title="Never expose the HTTP endpoint publicly">
It binds to `127.0.0.1` by default. Reach it **only** over the LAN or Tailscale. If you must front it with a reverse proxy, require mTLS (or OAuth) **and** an IP allowlist. Each agent authenticates with its own bearer token.
</Callout>

### C2. Point a remote agent at it

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

```json
{
  "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`](../cli/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`](../concepts/project-config) 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](tools) 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.