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

# MCP server

The **ALbuild MCP server** gives AI agents a real Business Central runtime. Over the
[Model Context Protocol](https://modelcontextprotocol.io), an assistant can provision (or warm-reuse) a
BC container, install dependencies from your feeds, publish apps and run the test suite against a live
instance, then read structured pass/fail results and iterate.

It closes the gap between *"it compiles"* and *"it actually runs and the tests pass against a specific
BC version"*, the fast inner loop **before** CI.

<Callout type="info" title="One engine, no drift">
Every tool is a thin, typed wrapper over a [`businessdev.ALbuild` PowerShell module](../powershell-module/index) cmdlet, the same engine that powers the CI/CD pipeline tasks and the VS Code extension. **Compilation is not its job** (that's the AL compiler / AL MCP); the MCP does *runtime validation*. CI remains the authoritative gate.
</Callout>

---

## Why

A full CI pipeline takes 15+ minutes. The MCP keeps a **warm** BC container and iterates
`deploy → test` in well under two minutes, so an agent (or you) can fix a failing test and re-run in
seconds. Container operations are **Windows + Docker only**: Business Central images are Windows-only, 
so the remote HTTP transport is the only way a Mac developer or agent gets real BC runtime validation.

<Callout type="tip" title="For a narrower question, there is something faster">
The MCP loop is the fastest way to answer *"does it run against a real BC?"*. It is not the fastest
way to answer *"what does this expression evaluate to?"*. For that,
[`albuild probe`](../cli/probe) interprets AL locally in a fraction of a second, with no container
at all. Probe is **CLI-only** and deliberately not an MCP tool: it answers a different question, and
an agent should reach for it first and fall back to the MCP loop when the answer depends on the real
platform.
</Callout>

---

## Transports

One binary, two transports, chosen at start:

| Transport | Start | Use |
| --- | --- | --- |
| **stdio** | `npx -y @365businessdev/albuild-mcp` | Local agent on a Windows box with Docker (Claude Code, the VS Code extension, Cursor). |
| **Streamable HTTP** | `albuild-mcp --http` | A shared Windows Server; remote agents (OpenClaw, Mac Claude Code) over LAN/Tailscale with a per-agent bearer token. |

---

## How AL developers get it

| You use… | How the MCP shows up |
| --- | --- |
| **VS Code** (Copilot agent mode) | The [ALbuild VS Code extension](../vscode-extension) contributes the `albuild` MCP server automatically, no manual config. |
| **Claude Code** (CLI / VS Code) | A small `.mcp.json` in your repo points at `npx @365businessdev/albuild-mcp`. |
| **OpenClaw / a Mac agent** | Connect over Streamable HTTP to a shared Windows MCP host with a bearer token. |

All three run the same npm package, [`@365businessdev/albuild-mcp`](https://www.npmjs.com/package/@365businessdev/albuild-mcp).
See the [step-by-step guide](get-started) to set up any of them.

---

## Architecture

```
        agent (any OS)                 MCP host (Windows + Docker)
   ┌───────────────────────┐        ┌─────────────────────────────────┐
   │ Claude Code / Copilot │ stdio  │  albuild-mcp (Node)             │
   │ OpenClaw / Cursor     │───────▶│    └─ businessdev.ALbuild (pwsh)│──▶ Docker / BC containers
   │                       │  HTTP  │         └─ New-BcContainer,     │──▶ artifact CDN
   └───────────────────────┘        │            Publish-/Test-…      │──▶ NuGet / Universal feeds
                                    └─────────────────────────────────┘
```

The agent never needs Docker or PowerShell itself, only the host does. A remote agent transports its
built `.app` files to the host as base64 (see [Tools → remote flow](tools#remote-app-and-dependency-flow)).

---

## Licensing

The MCP server is **free** and published under the MIT license. The ALbuild paid tier is enforced in the
PowerShell module it calls, not in the MCP. See [Licensing & Tiers](../concepts/licensing).

---

## Next steps

- **[Get started](get-started)**: install and wire up VS Code, Claude Code, or a remote HTTP host, then run the inner loop.
- **[Tools reference](tools)**: every tool, the async job model, the remote app/dependency flow, per-agent scoping and governance.