Set up Business Central MCP with bc-mcp-proxy
Connect Microsoft Dynamics 365 Business Central to Claude Desktop, VS Code or Cursor over MCP. From Azure App Registration to first AI query in 20 minutes.
This guide walks you through connecting your Business Central tenant to an AI client (Claude Desktop, VS Code, or Cursor) using bc-mcp-proxy. By the end you’ll be able to ask Claude “show me the top 10 customers by outstanding balance” and get the answer from your live BC data.
About 20 minutes if you’re comfortable with Azure portal. The Azure App Registration is the only finicky part — if you’d rather not deal with manifests and redirect URIs, book a free hands-on Setup Session and we do it together. (Launch promotion: setup sessions are free of charge through 30 June 2026 while we shape the offering.)
Prerequisites
| Item | Detail |
|---|---|
| BC environment | Version 28 or later is the default target (GA since May 2026). Versions 26 and 27 are still supported, but Microsoft frames that endpoint as preview until everyone is on v28 — expect occasional breaking changes there. Sandbox or production. The MCP feature is enabled out of the box. |
| 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.10+ or the prebuilt .dxt bundle | On your machine for the manual route, or install the published .dxt Claude Desktop Extension — Windows / macOS Apple Silicon / Linux x86_64 — which vendors all Python deps and skips the pip install step. |
If any of these are missing, get them sorted before continuing — the steps below assume all four.
What this proxy does
The BC MCP server speaks HTTP with Server-Sent Events. Claude Desktop, VS Code and Cursor speak stdio to their MCP servers, not HTTP. bc-mcp-proxy is the translator that runs locally on your machine:
It also handles the unglamorous-but-important parts: silent OAuth token refresh, exponential backoff reconnects on transient upstream errors, a three-tier tools/list cache that masks BC’s 30s+ first-call latency (which would otherwise trip Claude Desktop’s hardcoded MCP request timeout), and surfacing masked Business Central error messages that would otherwise be silently swallowed by your AI client.
Two install paths. The
pip installflow below works on every platform and supports any MCP-capable client (Claude Desktop, VS Code, Cursor). For Claude Desktop only, you can skip Steps 3-5 by installing the published.dxtbundle instead. Steps 1 and 2 (Azure App Registration + BC MCP Configuration) are required either way.
Step 1 — Create an Azure App Registration
In the Azure portal:
- Open Microsoft Entra ID → App registrations → New registration.
- Name it something recognisable, e.g.
BC MCP Proxy — production. - Supported account types: Accounts in this organizational directory only (single tenant).
- Leave the Redirect URI blank for now.
- Click Register. Note the Application (client) ID and Directory (tenant) ID — you’ll paste both into the proxy config.
Then back in the same app:
-
Authentication → Add a platform → Mobile and desktop applications → enter:
ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>Replace
<your-client-id>with the Application (client) ID from step 5. -
Lower on the same page, set “Allow public client flows” to Yes, and save.
Now permissions:
- API permissions → Add a permission → Dynamics 365 Business Central → Delegated permissions:
- Tick
Financials.ReadWrite.All(orFinancials.Read.Allfor read-only). - Tick
user_impersonation.
- Tick
- 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 clicking Grant admin consent are the signal that you’re done.
Step 2 — Create a BC MCP Configuration
In Business Central, in your target environment:
- Use the search box to find “MCP Server Configurations” (the page is also titled Model Context Protocol Server Configurations).
- Click + New.
- Fill in:
- Name: e.g.
Default MCP. The name flows through as a header — case and trailing whitespace matter, so keep it simple. - Active: switch on.
- Dynamic Tool Mode: see Static vs Dynamic below to choose.
- Discover Additional Objects (only relevant in Dynamic mode): tick to expose objects outside your toolset for read-only discovery.
- Name: e.g.
- Add System Tools or Available Tools as needed — start narrow, you can always expand.
- Save.
⚠️ The single most common pitfall: you save the page (BC shows “Saved”) but Active stays off by default. Without
Active = YesBC rejects every tool call with “The MCP Configuration named X was not found or not active.” Always double-check the toggle.
Tip: create two configurations with the same toolset, one with
Active = Noand oneActive = Yes. That way you can experiment without touching the live config.
Quick install (Claude Desktop, one-click .dxt)
If you only need Claude Desktop (not VS Code or Cursor), the published DXT bundle skips Steps 3-5 entirely. Pre-built bundles are attached to every GitHub Release with all Python dependencies vendored — no pip install step required.
-
Download the bundle for your platform from the latest release:
Platform Asset Windows 64-bit bc-mcp-proxy-<version>-win-amd64.dxtmacOS Apple Silicon bc-mcp-proxy-<version>-darwin-arm64.dxtLinux x86_64 bc-mcp-proxy-<version>-linux-x86_64.dxt -
Double-click the file. Claude Desktop opens an install dialog.
-
Fill in Tenant ID, Client ID, Environment, Company, optional Configuration Name. The defaults already point at the BC v28 endpoint; override via the Business Central MCP endpoint field for v26/v27.
-
Restart Claude Desktop, then jump to Step 6 — First sign-in.
The manual pip install route below is the right path if you want VS Code / Cursor support, you want to inspect or modify the proxy code, or you’re on Intel macOS — no pre-built .dxt is published for Intel Mac, but ./dxt/build.sh produces an identical bundle on any Apple-Silicon-or-Intel Mac with Python 3.10+.
Step 3 — Install the proxy
Install from PyPI (recommended):
python -m pip install --upgrade 360solutions-bc-mcpOr from source if you want to inspect or modify the code:
git clone https://github.com/360solutionsbe/bc-mcp-proxy.git
cd bc-mcp-proxy
python -m pip install -e .Verify the install:
python -m bc_mcp_proxy --helpYou should see the help text listing CLI flags.
Step 4 — Configure the proxy
Create a .env file next to where you’ll launch the proxy from:
BC_TENANT_ID=<your-tenant-id>
BC_CLIENT_ID=<your-client-id-from-step-1>
BC_ENVIRONMENT=Production
BC_COMPANY=CRONUS USA
BC_CONFIGURATION_NAME=Default MCPThat’s the minimum. The proxy now defaults to the BC v28 endpoint (Microsoft’s documented host for non-Microsoft MCP clients, generally available since May 2026). For environments still on v26 or v27, add:
BC_BASE_URL=https://api.businesscentral.dynamics.comThe proxy auto-switches both the OAuth scope and the request headers when you change BC_BASE_URL — there’s no second flag to flip.
The full set of configuration parameters is in the reference table at the end.
Step 5 — Wire it into your AI client
Claude Desktop
Edit Claude Desktop’s config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add an mcpServers entry:
{
"mcpServers": {
"business-central": {
"command": "python",
"args": [
"-m", "bc_mcp_proxy",
"--TenantId", "<your-tenant-id>",
"--ClientId", "<your-client-id>",
"--Environment", "Production",
"--Company", "CRONUS USA",
"--ConfigurationName", "Default MCP"
]
}
}
}Restart Claude Desktop. Your BC tools are now available in every chat.
VS Code or Cursor
Both support MCP via similar JSON config. The proxy ships an interactive setup wizard that generates ready-to-paste install links for Cursor and VS Code, plus a Claude Desktop snippet:
python -m bc_mcp_proxy setupFollow the prompts; it walks you through every value and writes the right config for you.
Step 6 — First sign-in
The very first tool call walks the device code flow. You’ll see something like:
To sign in, use a web browser to open https://microsoft.com/devicelogin
and enter the code ABCD-1234 to authenticate.Open the URL, paste the code, sign in with the Azure account that has BC permissions. Your token is then cached locally (via msal-extensions with platform-specific secure storage — DPAPI on Windows, Keychain on macOS, libsecret on Linux). Subsequent runs are non-interactive until expiry — at which point the proxy refreshes silently.
First test: ask your AI
Restart your AI client and try one of these:
- “Show me the top 5 customers in CRONUS USA.”
- “Which vendors have an outstanding balance over €5,000?”
- “List Sales Invoices from last month with status Open.”
In Static mode the AI picks the tool directly (e.g. ListCustomers_PAG30009) with parameters like top: 5. In Dynamic mode you’ll see three steps fire — bc_actions_search → bc_actions_describe → bc_actions_invoke. Both modes return the same data.
If you get a real answer, you’re done. If you don’t, head to Troubleshooting below.
What’s next — when BC MCP is the start, not the end
BC MCP is the fastest way to see whether AI agents fit your business — free, open-source, up in an afternoon. Most of our small-business customers ask the next question pretty quickly: “What about the rest of our systems?”
The same MCP plumbing extends to whatever else you run — CAD libraries, ERPs, custom databases, internal tools. The Fusion 360 case study is one example of what that looks like in practice: parametric CAD source → brand-aware A4 spec sheet, end-to-end via MCP in ~28 seconds.
See the Fusion 360 case study →
Two-week fixed-scope engagements, bespoke per system. We do, you watch.
Static vs Dynamic Tool Mode
| Static | Dynamic | |
|---|---|---|
| Tools the AI sees | One per selected page (e.g. 10 tools) | Three generic tools |
| First-call performance | Fast (sub-second) | Slow on first call (50–60s when Discover Additional Objects is on) |
| Subsequent calls | Fast | Fast — the catalog is cached |
| AI prompt cost | Higher (the AI sees all tool schemas) | Lower (only three meta-tools) |
| Best for | A bounded, explicit set of use cases | Flexible exploration across many pages |
Our recommendation: start with Static mode for your first test (fast feedback, you know exactly which tools exist). Switch to Dynamic once your users start asking things you didn’t preselect a tool for.
BC version compatibility
Microsoft changed the MCP endpoint shape in BC v28 and now documents only the v28 host for non-Microsoft MCP clients. The proxy detects which host you point it at and adapts URL shape, request headers, and OAuth scope automatically:
| BC version | BC_BASE_URL | URL shape | Routing headers | OAuth scope |
|---|---|---|---|---|
| 28+ (default) | https://mcp.businesscentral.dynamics.com | bare host, no path | TenantId + EnvironmentName (plus Company, ConfigurationName) | https://mcp.businesscentral.dynamics.com/.default |
| 26 / 27 | https://api.businesscentral.dynamics.com | /v2.0/{environment}/mcp appended | Company, ConfigurationName | https://api.businesscentral.dynamics.com/.default |
Switching is a single-line change in .env or via --BaseUrl; the scope and headers follow automatically. Set BC_TOKEN_SCOPE only if you need to override the auto-pick.
Cold-start mitigation
BC’s MCP endpoint can take 30s+ to answer the very first tools/list call after the environment has been idle, which is longer than Claude Desktop’s hardcoded MCP request timeout. The proxy masks this with a three-tier cache: on startup it loads the previously cached tools list from disk (per tenant/environment/company/configuration), then eagerly pre-warms tools/list once the upstream session connects, then answers the stdio handler from an in-memory 5-minute TTL cache instead of round-tripping to BC every call.
The very first install on a freshly cold-started BC environment may still hit the 30s timeout once — there’s no disk cache yet. Every subsequent launch is instant.
Configuration parameters
Full set of options:
| Parameter | CLI argument | Env var | Default |
|---|---|---|---|
| Tenant ID | --TenantId | BC_TENANT_ID | required |
| Client ID | --ClientId | BC_CLIENT_ID | required |
| Environment | --Environment | BC_ENVIRONMENT | Production |
| Company | --Company | BC_COMPANY | required |
| Configuration Name | --ConfigurationName | BC_CONFIGURATION_NAME | unset |
| Custom Auth Header | --CustomAuthHeader | BC_CUSTOM_AUTH_HEADER | unset (skips device flow when provided) |
| Base URL | --BaseUrl | BC_BASE_URL | https://mcp.businesscentral.dynamics.com (BC v28) |
| Token Scope | --TokenScope | BC_TOKEN_SCOPE | auto-picked from base URL host (set only to override) |
| HTTP Timeout (s) | --HttpTimeoutSeconds | BC_HTTP_TIMEOUT_SECONDS | 120.0 |
| SSE Timeout (s) | --SseTimeoutSeconds | BC_SSE_TIMEOUT_SECONDS | 300.0 |
| Log Level | --LogLevel | BC_LOG_LEVEL | INFO |
| Debug | --Debug | BC_DEBUG=1 | off |
Token cache locations (when no custom auth header is supplied):
- Windows:
%LOCALAPPDATA%\BcMCPProxyPython\bc_mcp_proxy.bin - macOS:
~/Library/Caches/BcMCPProxyPython/bc_mcp_proxy.bin - Linux:
$XDG_CACHE_HOME/BcMCPProxyPython/bc_mcp_proxy.bin
Troubleshooting
The MCP Configuration named X was not found or not active. Open the configuration in BC and verify the Active toggle is on. Saving the page does not flip Active automatically. The error also fires when the ConfigurationName header value differs from the BC record by even a trailing space.
Authentication failures. Verify the redirect URL format (ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientID>) and that “Allow public client flows” is enabled on the Azure app registration. Make sure all API permissions are granted and admin-consented. Rerun setup if the device flow times out.
Calls hang or time out (especially in Dynamic Tool Mode). The first bc_actions_search against a configuration with Discover Additional Objects enabled enumerates the entire metadata catalog — measured at 50–60s server-side on a Cronus demo. Raise BC_HTTP_TIMEOUT_SECONDS (default 120) if you see httpx.ReadTimeout on the first call. Subsequent calls within the same session are typically sub-second; the proxy’s cold-start cache keeps tools/list instant on every later launch.
JSON-RPC -32603 "An error occurred." with no detail. This is BC’s catch-all when something inside a Dynamic-tool call goes wrong. The actual reason is logged to Azure Application Insights as event RT0054 with custom dimension toolInvocationFailureReason. Enable telemetry on the BC environment and query:
traces
| where customDimensions.eventId == 'RT0054'
| where customDimensions.toolInvocationResult == 'Failure'Frequent reconnects in logs. Inspect upstream availability — the proxy logs Upstream connection error (...); reconnecting in Xs (attempt N/M) whenever it retries. After the configured budget the proxy gives up and the local stdio pipe closes.
Repeated sign-in prompts. The MSAL token cache may not be writable. Pass --DeviceCacheLocation to point at a directory you control.
No module named bc_mcp_proxy. Install the distribution into the same Python interpreter your MCP client is configured to launch — python -m pip install --upgrade 360solutions-bc-mcp.
Security model
- No application secrets. Delegated permissions only via the device-code flow. No client secret to manage or rotate.
- Tokens cached locally with OS-specific secure storage (DPAPI on Windows, Keychain on macOS, libsecret on Linux). No plaintext on disk.
- No tokens in logs. The proxy never logs access or refresh tokens; debug output contains only expiry timestamps for diagnosis.
- Permissions are delegated. Whatever the proxy can see and do, the signed-in user could already do manually in BC. The AI gets no extra rights.
- Configuration name as gate. In BC you decide per MCP Configuration which pages and objects are exposed. Put sensitive data behind a separate configuration that you only flip Active for specific users.
Need help?
The Azure App Registration takes attention to detail. For customers who would rather not deal with Manifest.json, redirect URIs and delegated permissions themselves, 360 Solutions offers an end-to-end hands-on Setup Session — free of charge through 30 June 2026 (60–90 min):
- Azure App Registration created and validated in your tenant
- BC MCP Configuration created on the right environment(s)
- Proxy plus AI client (Claude Desktop, VS Code or Cursor) installed and tested on your workstation
- Short user training: which questions work well, which don’t, what the privacy and cost trade-offs look like
- Optional: Application Insights telemetry hookup so you can see who uses which tools later
Book a free 30-min discovery call first to see if it’s a fit — no commitment.
📦 360solutions-bc-mcp on GitHub · MIT-licensed
📧 dev@360solutions.be