# d365-bc-mcp

A **read-only [MCP](https://modelcontextprotocol.io) server for Dynamics 365 Business Central**. It gives Claude Code, Claude Desktop, or any MCP client governed access to live ERP data — customers, items, orders, invoices, and any other BC API entity — without ever being able to change anything.

Built by an IT admin who wanted AI assistance over production ERP data and refused to hand an LLM write access to the general ledger to get it.

**Every tool issues GET requests only.** Nothing is created, modified, or deleted in Business Central, by construction — there is no code path that issues a write.

## Design

- **Read-only by construction, then again by permission.** The server only performs GETs, and the recommended setup *also* runs under an identity that BC itself restricts to read-only permission sets. Two independent layers; either alone would hold.
- **Dual auth, auto-selected.** Personal use gets delegated device-code auth (BC sees *you*, your permissions apply). Shared/deployed use gets client-credentials with a dedicated Entra app. Set one env var to switch.
- **Two transports.** stdio for local MCP clients; stateless Streamable HTTP (`--http`) for remote/shared use, with optional bearer-key protection.
- **Boring dependencies.** TypeScript, `@modelcontextprotocol/sdk`, MSAL, Express, Zod. No framework, ~2.5k lines, readable in one sitting.

| Mode | When | How it authenticates |
|---|---|---|
| `device_code` (default) | `BC_CLIENT_SECRET` empty | Delegated — you sign in once as yourself; BC sees your user and your BC permissions apply |
| `client_credentials` | `BC_CLIENT_SECRET` set | Service-to-service — a dedicated Entra app with its own (read-only) BC permission set |

## Prerequisites

- Node.js 20+
- A Business Central online tenant and an Entra app registration:
  - **Device-code mode:** a public-client app registration — *Authentication → Allow public client flows: Yes*, plus the **delegated** `Dynamics 365 Business Central / user_impersonation` API permission. If your org already has one (many BC integrations create one), you can reuse it.
  - **Client-credentials mode:** see [Service-to-service setup](#service-to-service-setup-for-a-shared-connector) below.

## Quick start (device code)

```bash
git clone https://github.com/vinaybabuv/d365-bc-mcp
cd d365-bc-mcp
npm install
npm run build
cp .env.example .env   # then edit: tenant ID, client ID, environment, company
```

Sign in once, then verify the pipe end to end:

```bash
node --env-file=.env dist/index.js login
node --env-file=.env dist/index.js test
```

`login` runs the device-code flow (open the URL, enter the code) and caches tokens at `%LOCALAPPDATA%\d365-bc-mcp\token-cache.json` (override with `BC_TOKEN_CACHE`) — refresh is silent from then on. `test` lists companies and three sample customers to prove auth, environment, and company selection all work.

## Hook up to Claude Code

```bash
claude mcp add bc \
  --env BC_TENANT_ID=<your-tenant-guid> \
  --env BC_CLIENT_ID=<your-app-client-id> \
  --env BC_ENVIRONMENT=Production \
  --env "BC_COMPANY_NAME=CRONUS USA, Inc." \
  -- node /path/to/d365-bc-mcp/dist/index.js
```

(Add `--scope user` to make it available in every project.)

## Hook up to Claude Desktop

Add to `claude_desktop_config.json` (`%APPDATA%\Claude\` on Windows, `~/Library/Application Support/Claude/` on macOS) under `mcpServers`:

```json
{
  "mcpServers": {
    "business-central": {
      "command": "node",
      "args": ["/path/to/d365-bc-mcp/dist/index.js"],
      "env": {
        "BC_TENANT_ID": "<your-tenant-guid>",
        "BC_CLIENT_ID": "<your-app-client-id>",
        "BC_ENVIRONMENT": "Production",
        "BC_COMPANY_NAME": "CRONUS USA, Inc."
      }
    }
  }
}
```

## Service-to-service setup (for a shared connector)

For a connector that runs without a signed-in user (deployed to a server, used by a team), create a dedicated app registration:

**Task 1 — Entra** (entra.microsoft.com → App registrations → New):
1. Single tenant, no redirect URI needed.
2. *Certificates & secrets → New client secret* — copy the value immediately.
3. *API permissions → Add → Microsoft APIs → Dynamics 365 Business Central → **Application permissions** → `API.ReadWrite.All`* → Add, then **Grant admin consent**.
   (The permission name says ReadWrite, but actual data access is governed by the BC permission set you assign in Task 2 — assign a read-only one.)

**Task 2 — Business Central:**
1. In BC, search **Microsoft Entra Applications** → New.
2. Paste the app's **Application (client) ID**, set **State = Enabled**.
3. Assign a **read-only permission set** (e.g. `D365 READ` plus the specific read sets your data needs). Least privilege is the point: even though the server never writes, the identity it runs as shouldn't be *able* to.

**Then:** set `BC_CLIENT_ID` to the new app's ID and `BC_CLIENT_SECRET` to the secret. The server switches to client-credentials mode automatically. Verify with `node --env-file=.env dist/index.js test`.

## HTTP mode (remote / shared use)

```bash
node --env-file=.env dist/index.js --http
```

Serves stateless Streamable HTTP at `http://localhost:3010/mcp` (`PORT` to change), plus `GET /healthz`. Set `MCP_API_KEY` to require `Authorization: Bearer <key>` on every MCP request — do this for anything beyond localhost, and put real TLS in front of anything beyond your machine.

Connect Claude Code to it:

```bash
claude mcp add --transport http bc http://localhost:3010/mcp --header "Authorization: Bearer <MCP_API_KEY>"
```

**Note on claude.ai custom connectors:** claude.ai (Settings → Connectors) requires either an unauthenticated URL or OAuth — it cannot send a static bearer header. To expose this server there, put an OAuth layer in front (Entra ID works; claude.ai supports manually-entered client credentials), or use Microsoft's hosted Business Central MCP server instead. Claude Code and Claude Desktop work fine with the bearer-key approach.

## Tools

All list tools accept `top` (default 20, max 100) and `skip`, and return `{ total_count, returned, has_more, records }`.

| Tool | What it does |
|---|---|
| `bc_list_companies` | Companies visible to this connection |
| `bc_list_customers` | Customers; `search` on name or raw OData `filter` |
| `bc_get_customer` | One customer by number or GUID |
| `bc_list_items` | Items; `search`/`filter` (e.g. `inventory lt 10`) |
| `bc_list_vendors` | Vendors; `search`/`filter` |
| `bc_list_sales_orders` | Orders; by customer, status, date range |
| `bc_get_sales_order` | One order incl. lines, by number or GUID |
| `bc_list_sales_invoices` | Invoices; by customer, status, dates, `unpaid_only` |
| `bc_get_sales_invoice` | One invoice incl. lines, by number or GUID |
| `bc_query` | Read-only escape hatch: GET any BC API entity (`salesShipments`, `purchaseOrders`, `generalLedgerEntries`, …) or custom APIs via `api_route: "publisher/group/version"` |

## Environment variables

| Var | Required | Notes |
|---|---|---|
| `BC_TENANT_ID` | yes | Entra tenant GUID |
| `BC_CLIENT_ID` | yes | App registration client ID |
| `BC_CLIENT_SECRET` | no | Setting it switches to client-credentials mode |
| `BC_AUTH_MODE` | no | Explicit override: `device_code` \| `client_credentials` |
| `BC_ENVIRONMENT` | no | BC environment name, default `Production` |
| `BC_COMPANY_NAME` | no | Working company; auto-selected if the identity sees exactly one |
| `BC_TOKEN_CACHE` | no | Token cache path (device-code mode) |
| `MCP_API_KEY` | no | HTTP mode: require this bearer token |
| `PORT` | no | HTTP mode port, default 3010 |

## Security notes

- No secrets in code or in this repo — configuration is environment-only, and `.env` / token caches are git-ignored.
- Delegated mode inherits the signed-in user's BC permissions; it can never see more than that user could.
- Client-credentials mode should run under a BC permission set that is read-only, so the transport-level GET-only guarantee is backed by an authorization-level one.
- The HTTP transport is stateless and unauthenticated by default for localhost development; set `MCP_API_KEY` (and TLS) before exposing it anywhere else.

## License

MIT