VGS-BC-MCP

Fork of microsoft/BCTech samples/BcMCPProxyPython — a resilient Python MCP stdio proxy that bridges Claude Desktop, VS Code, Cursor and other MCP-compatible clients to the Microsoft Dynamics 365 Business Central MCP HTTP endpoint.

Built and maintained by Vangelder Solutions. Original: Copyright (c) Microsoft Corporation. Modifications: Copyright (c) 2026 Vangelder Solutions. Licensed under the MIT License.

✅ BC v28 (2026 release wave 1) and v29 (2026 release wave 2, GA October 2026). Microsoft's Business Central MCP server is generally available from version 28 onward on a single header-routed endpoint, and this proxy targets it by default. Version 29 keeps that contract and adds data-query and report-inbox tools, which the proxy forwards unchanged. The v26/v27 per-environment endpoint that preceded it was a preview; it is still supported here as an explicit legacy path for environments that haven't upgraded.

The proxy itself is MIT-licensed open source, actively maintained, with a 230+ test suite and Snyk-monitored dependencies. Suitable for development, evaluation, and pilot deployments. Production fitness is your organisation's call — see Security for the threat model.

---

TL;DR

• What you get: ask Claude (or another AI client) "show me the top 10 customers in CRONUS USA by outstanding balance" and it pulls that data live from your BC environment over a secure, authenticated connection. No exports, no copy-paste, no intermediate step.
• What it costs: nothing in licenses — MCP is built into BC starting from version 26 (May 2025 release wave). You choose your AI client (Claude Desktop is free for personal use).
• The hard part: creating an Azure App Registration with the right permissions. Ten minutes for someone IT-comfortable; the toughest part for everyone else. We're happy to help — see the Need help? section.

Quick install (Claude Desktop)

Pre-built .mcpb bundles (MCP Bundle, the successor of the .dxt format — older .dxt releases still install) are published on each release with all Python dependencies vendored — no pip install step required.

1. Download the bundle for your platform from the latest release:

   | Platform | Asset | |---|---| | Windows 64-bit | vgs-bc-mcp-<version>-win-amd64.mcpb | | macOS Apple Silicon | vgs-bc-mcp-<version>-darwin-arm64.mcpb | | Linux x86_64 | vgs-bc-mcp-<version>-linux-x86_64.mcpb |

   Every release also ships SHA256SUMS.txt so you can verify the download.

   Intel macOS (x86_64) is not shipped as a pre-built asset — Apple Silicon has been the default since 2020 and the audience for Intel-only Macs is vanishing. Intel Mac users can build from source via ./dxt/build.sh (any Mac with Python 3.10+).

2. Double-click the downloaded file. Claude Desktop opens an install dialog.

3. Fill in Tenant ID, Client ID, Environment, Company, (optional) Configuration Name. The defaults already point at the BC v28/v29 endpoint; override via the Business Central MCP endpoint field for v26/v27.

4. Restart Claude Desktop.

That's the whole install. The Azure App Registration setup is the only remaining step — see Step 1 — Azure App Registration below, or contact us via the Need help? section if you'd prefer it done for you.

Building from source (pwsh dxt/build.ps1 or ./dxt/build.sh) produces an identical bundle. Use the build path if you want to inspect the artifact, customise the manifest, or ship a private fork.

What this fork adds

• ✅ Reconnect on transient upstream errors. httpx.ReadTimeout, RemoteProtocolError, and NetworkError (including the same errors wrapped in an ExceptionGroup by anyio) trigger an exponential backoff reconnect — 1s → 2s → 4s → 8s → 16s, default 5 attempts. The local stdio pipe to your MCP client stays open while reconnecting.
• ✅ Pre-emptive MSAL silent token refresh. Each acquired access token's expiry is tracked locally; when remaining validity drops below token_refresh_skew_seconds (default 300) the next call asks MSAL to mint a new token via acquire_token_silent(force_refresh=True) instead of letting Business Central reject the stale one with Authentication_InvalidCredentials.
• ✅ Surface masked upstream errors. Some Business Central MCP responses ship with isError: false but the content is actually an error message ("Semantic search is not enabled", "Authentication_InvalidCredentials", etc.). The proxy now flags those as real MCP errors so the client sees them.
• ✅ BC v28 endpoint support. Auto-detects mcp.businesscentral.dynamics.com and switches to the new header-based routing (TenantId + EnvironmentName headers) while keeping v26/v27 behaviour intact.
• ✅ Cold-start mitigation. Three-tier tools/list cache (disk → in-memory pre-warm → upstream) masks BC's 30s+ first-call latency that otherwise trips Claude Desktop's hardcoded MCP request timeout. See Cold-start mitigation.
• ✅ SSRF hardening. BC_BASE_URL is validated at startup: scheme must be https, host must be *.businesscentral.dynamics.com. Override via BC_ALLOW_NON_STANDARD_BASE_URL=1 for local mock testing.
• ✅ Pinned transitive dependencies. Explicit security floors for h11, cryptography, pyjwt, python-multipart, starlette, urllib3, requests, python-dotenv — eliminates 16 CVE paths Snyk flagged in the upstream mcp/msal/httpx transitive trees. See SECURITY.md.
• ✅ Pytest test suite. 95 tests cover error classification, backoff progression, MSAL refresh-skew boundaries, masked-error pattern matching, v28 endpoint detection, OAuth scope auto-switch, the persistent tools cache, and base_url validation.

The CLI surface is unchanged — every flag and env var from the upstream sample still works.

---

What is the Model Context Protocol?

MCP is an open standard Anthropic published in 2024, since adopted by OpenAI, Microsoft and most of the AI tooling industry. It solves one problem: how do you give an AI assistant safe access to your data and systems without building a bespoke integration for every combination?

• An MCP server sits on the side of the system that exposes data or actions — in our case, Business Central.
• An MCP client is the AI tool the user interacts with — Claude Desktop, VS Code Copilot, Cursor, ChatGPT desktop with MCP support.
• Between them, tools are exchanged in a standardised format: name, description, parameter schema, and the result of an invocation.

Microsoft has, since Business Central 2025 release wave 1 (version 26), shipped a built-in MCP server in every BC environment. It listens on a Microsoft-hosted endpoint, validates your OAuth token, and exposes your configuration as a set of tools the AI client can call.

What this proxy does (and why you need it)

The BC MCP server speaks HTTP — a streamable-HTTP variant with Server-Sent Events. Most AI clients (Claude Desktop, VS Code, Cursor) run locally on your machine and speak stdio to their MCP servers, not HTTP.

The proxy is the translator:

┌─────────────────┐  stdio    ┌──────────────────┐  HTTPS + OAuth   ┌────────────────────────┐
│  Claude Desktop │ ◄────────►│ bc-mcp-proxy     │ ◄───────────────►│ Business Central MCP   │
│  / VS Code      │           │ (on your machine)│                  │ (Microsoft-hosted)     │
└─────────────────┘           └──────────────────┘                  └────────────────────────┘

---

Prerequisites

| Item | Detail | |---|---| | BC environment | Version 28.0 or later recommended (v29 supported); v26/v27 still work on the legacy endpoint. Sandbox or production. Read-only access to all API pages works out of the box; writes need an MCP Server Configuration with Unblock Edit Tools on. | | Microsoft Entra (Azure AD) tenant | With administrator rights — you'll create an App Registration and grant API permissions. | | An AI client | Claude Desktop (free), VS Code with MCP support, Cursor, or any other stdio-MCP capable tool. | | Python 3.11+ on your machine | Claude Desktop launches the proxy with the system python3. The .mcpb bundle vendors all Python dependencies internally (wheels for Python 3.11–3.14 of the host platform), so no separate pip install is required. |

---

Step-by-step setup

Step 1 — Azure App Registration

In the Azure portal:

1. Open Microsoft Entra ID → App registrations → New registration.
2. Name it something recognisable, e.g. BC MCP Proxy — production.
3. Supported account types: Accounts in this organizational directory only (single tenant).
4. Leave the Redirect URI blank for now.
5. Click Register. Note the Application (client) ID and Directory (tenant) ID.

Then in the same app:

6. Authentication → Add a platform → Mobile and desktop applications, then:
   • Tick the http://localhost checkbox. (Required.) The proxy signs you in with an interactive browser flow that redirects back to a localhost loopback listener — Microsoft Entra allows any port on http://localhost for public clients, so the checkbox is all you need (no port to specify). Without this you'll get AADSTS500113/AADSTS50011 and the proxy falls back to the slower device-code flow.
   • Also add the custom redirect URI (used by the device-code fallback):

     ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>
     

7. Lower on the same page: set "Allow public client flows" to Yes, save.

Permissions:

8. API permissions → Add a permission → Dynamics 365 Business Central → Delegated permissions:
   • Tick Financials.ReadWrite.All (or Financials.Read.All for read-only).
   • Tick user_impersonation.
9. Click Add permissions, then Grant admin consent for [tenant].

Without admin consent the first sign-in will fail. The green checkmarks next to each permission after Grant admin consent are the signal that you're done.

Step 2 — Create a BC MCP Configuration

In Business Central, in your target environment:

1. Search for "MCP Server Configurations" (the page is also titled Model Context Protocol Server Configurations).
2. Click + New.
3. Fill in:
   • Name: e.g. Default MCP. The name flows through as a header — case and trailing whitespace matter.
   • Active: switch on. ← The most common pitfall: you save the page (BC shows "Saved"), but Active is off by default. Without Active = Yes BC rejects every tool call with "The MCP Configuration named X was not found or not active".
   • Dynamic Tool Mode:
     • Off (Static mode) — BC generates one List_<EntityName>_PAG<id> tool per selected page. Predictable, fast, but you ch