sshadows/business-central-mcp

business-central-mcp

Give AI assistants direct access to Microsoft Dynamics 365 Business Central.
Native WebSocket protocol -- no OData, no APIs, no browser automation.

---

Overview

Install

BC Online (sandbox / production): do not put a password in env. Copy the portal URL from your browser and follow SaaS sandbox setup. The snippets below are for on-prem NavUserPassword.

VSCode

Click the badge. VSCode opens and prompts for your BC URL, username, and password (on-prem), then writes the configured entry to your user mcp.json. For BC Online, skip the badge and use the SaaS sandbox env (URL + optional email only).

Claude Code

claude mcp add business-central \
  -e BC_BASE_URL=http://your-bc-server/BC \
  -e BC_USERNAME=you \
  -e BC_PASSWORD=secret \
  -- npx -y business-central-mcp

Scope it to the current project with --scope project. See claude mcp --help for scoping options.

BC Online (no password):

claude mcp add business-central \
  -e BC_BASE_URL=https://businesscentral.dynamics.com//DEV \
  -e [email protected] \
  --scope project \
  -- npx -y business-central-mcp

Claude Desktop

1. Download the latest .dxt from Releases.
2. Double-click. Claude Desktop opens Settings → Extensions and prompts for BC URL, username, and password (on-prem). For BC Online, use the manual snippet instead — do not store a SaaS password.
3. Restart Claude Desktop.

Configuration

Central connection config

Running several Claude Code sessions against several BC instances no longer requires a full BC_* env block in every repo’s .mcp.json. Register the server once at user scope and define the connections in one file.

1. Register the server globally:

   claude mcp add business-central -s user -- node U:/git/bc-mcp/node_modules/tsx/dist/cli.mjs U:/git/bc-mcp/src/stdio-server.ts
   

2. Create ~/.bc-mcp/config.jsonc (see config.jsonc.example): a set of named connections, an optional default, and an optional map[] from repo path to connection.

3. Each session picks its connection, highest priority first:

   • an explicit BC_* env var (e.g. BC_BASE_URL) always wins for that field;
   • BC_CONNECTION= selects a named connection;
   • a map[] entry whose path matches the session’s working directory;
   • the default connection.

Keep secrets out of the file with ${ENV} references (expanded from the process environment); on macOS/Linux the file should be mode 0600. SaaS connections carry no password — sign in via the local window or npx business-central-mcp login. With no config file present, the server runs exactly as before from plain BC_* environment variables.

A /.env (or the file at BC_ENV_FILE) is also auto-loaded at startup, before connection resolution — real environment variables set outside the file still win (override:false).

On-prem containers: set BC_APPLICATION_ID=NAV

If sign-in and the WebSocket upgrade both succeed but the session dies at OpenSession with NavCancelCredentialPromptException, the server is rejecting the default applicationId (FIN). On-prem BcContainerHelper containers (the onprem artifact type) generally expect NAV:

BC_APPLICATION_ID=NAV

The failure is misleading because authentication and the /csh upgrade complete first (you get a 101); BC only rejects the applicationId inside the OpenSession RPC body. SaaS and cronus images keep the FIN default. Verified against BC 27.1 onprem (see issue #10).

SaaS sandbox setup

You only need the URL from the browser address bar — the same one you use to open Business Central Online:

https://businesscentral.dynamics.com//

`` is usually DEV, sandbox, or production. Do not set BC_PASSWORD. Company policy and this server both treat a SaaS password in env as wrong.

1. Copy that portal URL into BC_BASE_URL (no extra path, no query string).
2. Optionally set BC_USERNAME to your work email — that only prefills the sign-in form.
3. Point the MCP at this project (stdio, Grok .grok/config.toml, Claude --scope project, or a workspace mcp.json). Leave STATE_DIR unset so cookies land in {project}/.state/.
4. Start the agent on a machine with a display (Linux needs DISPLAY or WAYLAND_DISPLAY). Headless CI cannot complete MFA.
5. Ask the agent to open a page (bc_open_page, e.g. Customer List = 22). A local window (127.0.0.1) opens. Sign in with Microsoft and complete Authenticator there. Do not paste the password into chat or tool arguments.
6. Retry the tool. Cookies are saved as {project}/.state/saas-web-cookies.json (mode 0600). Later sessions in the same repo reuse them; another repo needs its own sign-in.

Human shortcut (same working directory as the MCP):

npx business-central-mcp login
# from a source checkout:
npx tsx src/stdio-server.ts login

Grok (project-scoped, no password):

# .grok/config.toml  — not committed if it holds a tenant URL you do not want shared
[mcp_servers.business-central]
command = "npx"
args = ["-y", "business-central-mcp"]

[mcp_servers.business-central.env]
BC_BASE_URL = "https://businesscentral.dynamics.com//DEV"
BC_USERNAME = "[email protected]"

From a source checkout, point command / args at node + node_modules/tsx/dist/cli.mjs + src/stdio-server.ts instead of npx.

Claude Desktop / VS Code (no BC_PASSWORD):

{
  "mcpServers": {
    "business-central": {
      "command": "npx",
      "args": ["-y", "business-central-mcp"],
      "env": {
        "BC_BASE_URL": "https://businesscentral.dynamics.com//DEV",
        "BC_USERNAME": "[email protected]"
      }
    }
  }
}

The WebSocket is not on the portal host. After sign-in the server discovers the cluster and uses Origin: https://businesscentral.dynamics.com. You never put a cluster URL in config.

bc_query (OData) on SaaS

bc_query does not use the /csh cookie session. When sign-in is needed the first call returns DEVICE_LOGIN_REQUIRED with a https://microsoft.com/devicelogin URL and user code — complete it in a browser and retry; the retry picks up the pending sign-in and runs the query. The refresh token is stored in STATE_DIR/oauth-tokens.json (mode 0600).

bc_query talks to https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/v2.0 with the Bearer token. If BC_CLIENT_ID is not configured it returns OAUTH_NOT_CONFIGURED (device-code that has not been completed returns DEVICE_LOGIN_REQUIRED, above); it never sends Basic.

Which client id signs in (BC_CLIENT_ID)

BC_CLIENT_ID is required for bc_query on BC Online: a multi-tenant public Entra app with delegated Dynamics 365 Business Central / user_impersonation. The publisher registers it ONE time in their own tenant; customer tenants register nothing — each user consents at first sign-in (user_impersonation is user-consentable), and tenants that disable user consent need a one-time admin-consent click.

Do not borrow a Microsoft first-party client (Azure PowerShell 1950a258-… as New-BcAuthContext does, Azure CLI, …): on tenants with Entra first-party hardening the sign-in fails in the browser with AADSTS65002 (“consent between first party application and first party resource must be configured via preauthorization”), which no tenant admin can consent around. Verified live 2026-08-16 — the same sign-in succeeds on one tenant and fails with 65002 on another. A third-party multi-tenant app is structurally immune (65002 only gates Microsoft-owned client/resource pairs).

Create the app (once, in the publisher tenant):

az ad app create --display-name "business-central-mcp" \
  --is-fallback-public-client true \
  --sign-in-audience AzureADMultipleOrgs \
  --required-resource-accesses '[{"resourceAppId":"996def3d-b36c-4153-8607-a6fd3c01b89f","resourceAccess":[{"id":"bce0976a-cb0b-473b-8800-84eda9f8e447","type":"Scope"}]}]' \
  --query appId -o tsv

(996def3d… is the Dynamics 365 Business Central resource; bce0976a… is its delegated user_impersonation scope.) Put the printed appId in BC_CLIENT_ID.

Known wart: when the browser sign-in fails (65002, blocked consent), Entra keeps the device code authorization_pending, so retries re-serve the same doomed code until it expires (~15 min). Fix the client id / consent, wait out or ignore the old code, and retry for a fresh one.

What can it do?

Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so clients can auto-approve the read-only ones and ask before writes, actions, dialogs, reports and uploads.

The eight tools that change state accept an optional operationId (an idempotency key you generate). A retry with the same id and arguments returns the first call’s stored result instead of running the change again, so retrying after a timeout or dropped connection cannot double-post. The same id with different arguments returns OPERATION_ID_REUSED. If the first call’s outcome is unknown (timeout, session loss), the retry returns OPERATION_IN_DOUBT: check the record before acting under a new id. That response carries a target snapshot taken before the first call ran (company, page id and caption, section, the targeted rows’ cell values, dialog), so you can find the record again even though the original pageContextId died with the session. Calls are recorded in STATE_DIR/operations/, so this survives a server restart.

Replay is time-limited. The server prunes the ledger at start and hourly: a completed entry is deleted after BC_OPERATION_TTL (default 24 hours), after which a retry with the same id runs the call again, so check with bc_get_operation before a late retry. sent/unknown entries are kept for BC_OPERATION_INDOUBT_TTL (default 30 days). Download bytes are not stored: a replayed result lists each download’s fileName, contentType, sizeBytes and savedPath (set when BC_DOWNLOAD_DIR is configured), but not its bytes; each such entry carries error.code: "NOT_REPLAYED" so it is never mistaken for a successful capture.

Every result from those eight tools (and its ledger entry) carries replaySafe. true means BC’s response proved that re-running the same call, even under a new operationId after an unknown outcome, cannot apply the change twice. false means a re-run may double-apply, or nothing in the response proved otherwise: read the record back first. The server only says true when it can prove it:

An OPERATION_IN_DOUBT response is always replaySafe: false, and so is the first error response to an ambiguous failure (TIMEOUT_ERROR, SESSION_LOST, CONNECTION_ERROR, PROTOCOL_ERROR, ABORTED_ERROR, or an unclassified error), with or without an operationId: it is in structuredContent next to the error code. Definite failures (validation, business errors) carry no verdict, because nothing was applied.

bc_get_operation { operationId } (read-only) returns the ledger entry: status, tool, timestamps, replaySafe, the stored result and the target snapshot. When the status is not completed or replaySafe is false, it also re-reads the target in the current session: it re-opens the page by page id on the recorded record bookmark, reads the record’s primary-key fields (by table field number, from the page’s own key metadata; a key field with no control on the page, such as a Sales Order’s “Document Type”, is decoded from the record bookmark and marked source: "bookmark", with an option as its ordinal; a key that no longer matches returns readBackError: KEY_MISMATCH without an evidenceHash) plus any written fields (or the targeted list row, null if it is gone; a document header also gets its loaded lines, since a posting changes line state such as “Quantity Shipped” but not the header key fields), closes the page, and returns that as readBack with evidenceHash, the SHA-256 of its sorted-key JSON. It does not switch company for you (readBackError: COMPANY_MISMATCH), does not open a page while a dialog is open (MODAL_OPEN: opening would cancel it; answer it first), and never re-opens a page without a recorded record bookmark (NO_TARGET). A card in edit mode keeps a written value until the page is closed or leaves the record, so a read-back taken while the original page is still open can show the old value.

The HTTP transport’s REST API (POST /api/v1/...) uses the same ledger. Its three mutating routes take the key in an Idempotency-Key header and record it under their MCP tool name (pages/write = bc_write_data, pages/action = bc_execute_action, pages/close = bc_close_page), so a key means the same operation on both transports and bc_get_operation can look up a REST call. Responses:

Ambiguous failures (503/504/500) of a mutating route carry replaySafe: false, with or without a key. Read-only routes ignore the header.

How it works

This server speaks BC’s internal WebSocket protocol directly – the same protocol the browser-based web client uses. It was reverse-engineered from decompiled BC server assemblies. No OData endpoints, no SOAP services, no Selenium.

One WebSocket connection per session. All operations serialized through a promise queue. BC27 and BC28 are wire-compatible.

LLM (Claude / Copilot / etc.)
   |
   v   MCP (stdio or HTTP)
business-central-mcp
   |
   v   WebSocket + JSON-RPC
BC Web Service Tier (BC27 / BC28)
   |
   v   internal calls
BC Server

Key files

Development

git clone https://github.com/SShadowS/business-central-mcp
cd business-central-mcp
npm install
npm run start:stdio-direct   # Run from source
npm test                     # unit + protocol tests
npm run test:integration     # Cronus28 integration tests (requires running BC server)
npm run test:saas            # BC Online smoke (needs a signed-in STATE_DIR cookie file)

Roadmap

Cursor support, an interactive init wizard, and a few protocol gaps. See ROADMAP.md for the full list and priorities.

---

Author: Torben Leth ([email protected]) License: MIT (see LICENSE)