Business Central MCP opzetten met bc-mcp-proxy
Koppel Microsoft Dynamics 365 Business Central aan Claude Desktop, VS Code of Cursor via MCP. Van Azure App Registration tot eerste AI-vraag in 20 minuten.
Deze gids leidt u door het koppelen van uw Business Central-tenant aan een AI-client (Claude Desktop, VS Code of Cursor) via bc-mcp-proxy. Op het einde kunt u Claude vragen “toon mij de top 10 klanten met openstaande saldo” en krijgt u het antwoord uit uw live BC-data.
Ongeveer 20 minuten als u comfortabel bent met de Azure-portal. De Azure App Registration is het enige delicate deel — als u liever niet zelf met manifests en redirect-URI’s worstelt, boek een gratis hands-on Setup Session en we doen het samen. (Lanceeractie: setup sessions zijn gratis tot 30 juni 2026 terwijl we het aanbod vormgeven.)
Vereisten
| Onderdeel | Detail |
|---|---|
| BC-omgeving | Versie 28 of later is het standaarddoel (GA sinds mei 2026). Versies 26 en 27 worden nog ondersteund, maar Microsoft framet dat endpoint als preview tot iedereen op v28 zit — verwacht daar af en toe breaking changes. Sandbox of productie. MCP staat standaard aan. |
| Microsoft Entra (Azure AD)-tenant | Met administrator-rechten — u maakt een App Registration aan en geeft API-permissies. |
| Een AI-client | Claude Desktop (gratis), VS Code met MCP-ondersteuning, Cursor of een ander stdio-MCP-tool. |
Python 3.10+ of de prebuilt .dxt-bundle | Op uw machine voor de manuele route, of installeer de gepubliceerde .dxt Claude Desktop Extension — Windows / macOS Apple Silicon / Linux x86_64 — die alle Python-deps vendort en de pip install-stap overslaat. |
Als één van deze ontbreekt, regel dat eerst — de stappen hieronder veronderstellen alle vier.
Wat deze proxy doet
De BC MCP-server praat HTTP met Server-Sent Events. Claude Desktop, VS Code en Cursor praten stdio met hun MCP-servers, geen HTTP. bc-mcp-proxy is de vertaler die lokaal op uw machine draait:
De proxy regelt ook de minder zichtbare maar belangrijke stukken: silent OAuth token-refresh, exponential backoff reconnects bij tijdelijke upstream-fouten, een drie-laagse tools/list-cache die BC’s 30s+ first-call-latency maskeert (die anders Claude Desktop’s hardcoded MCP-request-timeout zou tripperen), en het zichtbaar maken van Business Central-foutmeldingen die anders stilletjes door uw AI-client zouden worden ingeslikt.
Twee installatiepaden. De
pip install-flow hieronder werkt op elk platform en ondersteunt elke MCP-capable client (Claude Desktop, VS Code, Cursor). Voor alleen Claude Desktop kunt u Stappen 3-5 overslaan door in plaats daarvan de gepubliceerde.dxt-bundle te installeren. Stappen 1 en 2 (Azure App Registration + BC MCP Configuration) zijn in beide gevallen nodig.
Stap 1 — Azure App Registration aanmaken
In de Azure-portal:
- Open Microsoft Entra ID → App registrations → New registration.
- Geef een herkenbare naam, bv.
BC MCP Proxy — production. - Supported account types: Accounts in this organizational directory only (single tenant).
- Laat de Redirect URI voorlopig leeg.
- Klik Register. Noteer de Application (client) ID en Directory (tenant) ID — beide plakt u straks in de proxy-config.
Daarna in dezelfde app:
-
Authentication → Add a platform → Mobile and desktop applications → vul in:
ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>Vervang
<your-client-id>met de Application (client) ID uit stap 5. -
Lager op dezelfde pagina: zet “Allow public client flows” op Yes en bewaar.
Dan permissies:
- API permissions → Add a permission → Dynamics 365 Business Central → Delegated permissions:
- Vink
Financials.ReadWrite.Allaan (ofFinancials.Read.Allvoor read-only). - Vink
user_impersonationaan.
- Vink
- Klik Add permissions, dan Grant admin consent for [tenant].
Zonder admin consent faalt de eerste sign-in. De groene vinkjes naast elke permissie na het klikken op Grant admin consent zijn het signaal dat het in orde is.
Stap 2 — Maak een BC MCP Configuration
In Business Central, in uw doel-omgeving:
- Zoek via de zoekbalk naar “MCP Server Configurations” (de pagina heet ook Model Context Protocol Server Configurations).
- Klik + New.
- Vul in:
- Name: bv.
Default MCP. De naam stroomt door als header — case en trailing whitespace tellen, dus houd het simpel. - Active: zet aan.
- Dynamic Tool Mode: zie Static vs Dynamic hieronder.
- Discover Additional Objects (alleen relevant in Dynamic mode): aanvinken om read-only discovery te activeren voor objecten buiten uw toolset.
- Name: bv.
- Voeg System Tools of Available Tools toe naar gelang. Begin smal — uitbreiden kan later altijd.
- Save.
⚠️ De allerbekendste valkuil: u bewaart de pagina (BC toont “Saved”) maar Active blijft standaard uit. Zonder
Active = Yesweigert BC elke tool-call met “The MCP Configuration named X was not found or not active.” Controleer altijd dubbel.
Tip: maak twee configuraties met dezelfde toolset, één met
Active = Noen één metActive = Yes. Zo kunt u experimenteren zonder de live config aan te raken.
Quick install (Claude Desktop, één-klik .dxt)
Hebt u alleen Claude Desktop nodig (geen VS Code of Cursor), dan slaat de gepubliceerde DXT-bundle Stappen 3-5 volledig over. Pre-built bundles worden bij elke GitHub Release meegeleverd met alle Python-dependencies vendored — geen pip install-stap nodig.
-
Download de bundle voor uw platform vanaf de 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 -
Dubbelklik het bestand. Claude Desktop opent een installatiedialog.
-
Vul in Tenant ID, Client ID, Environment, Company, optioneel Configuration Name. De defaults wijzen al naar het BC v28-endpoint; override via het Business Central MCP endpoint-veld voor v26/v27.
-
Herstart Claude Desktop en spring naar Stap 6 — Eerste sign-in.
De manuele pip install-route hieronder is het juiste pad als u VS Code / Cursor-ondersteuning wilt, de proxy-code wilt inspecteren of aanpassen, of als u op Intel macOS zit — er wordt geen pre-built .dxt voor Intel Mac gepubliceerd, maar ./dxt/build.sh produceert op elke Mac met Python 3.10+ een identieke bundle.
Stap 3 — Installeer de proxy
Installeer vanuit PyPI (aanbevolen):
python -m pip install --upgrade 360solutions-bc-mcpOf vanuit de source als u de code wilt inspecteren of aanpassen:
git clone https://github.com/360solutionsbe/bc-mcp-proxy.git
cd bc-mcp-proxy
python -m pip install -e .Verifieer de installatie:
python -m bc_mcp_proxy --helpU zou de help-tekst met CLI-flags moeten zien.
Stap 4 — Configureer de proxy
Maak een .env bestand aan naast waar u de proxy wilt starten:
BC_TENANT_ID=<uw-tenant-id>
BC_CLIENT_ID=<uw-client-id-uit-stap-1>
BC_ENVIRONMENT=Production
BC_COMPANY=CRONUS USA
BC_CONFIGURATION_NAME=Default MCPDat is het minimum. De proxy wijst standaard naar het BC v28-endpoint (Microsoft’s gedocumenteerde host voor non-Microsoft MCP-clients, algemeen beschikbaar sinds mei 2026). Voor omgevingen die nog op v26 of v27 draaien, voegt u toe:
BC_BASE_URL=https://api.businesscentral.dynamics.comDe proxy switcht automatisch zowel de OAuth-scope als de request-headers wanneer u BC_BASE_URL wijzigt — er is geen tweede flag om om te zetten.
De volledige set parameters staat in de referentietabel onderaan.
Stap 5 — Koppel het aan uw AI-client
Claude Desktop
Bewerk het Claude Desktop-configbestand:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Voeg een mcpServers-blok toe:
{
"mcpServers": {
"business-central": {
"command": "python",
"args": [
"-m", "bc_mcp_proxy",
"--TenantId", "<uw-tenant-id>",
"--ClientId", "<uw-client-id>",
"--Environment", "Production",
"--Company", "CRONUS USA",
"--ConfigurationName", "Default MCP"
]
}
}
}Herstart Claude Desktop. Uw BC-tools zijn nu beschikbaar in elke chat.
VS Code of Cursor
Beide ondersteunen MCP via vergelijkbare JSON-config. De proxy heeft een interactieve setup-wizard die kant-en-klare install-links genereert voor Cursor en VS Code, plus een Claude Desktop-snippet:
python -m bc_mcp_proxy setupVolg de prompts; de wizard begeleidt u doorheen elke waarde en schrijft de juiste config voor u.
Stap 6 — Eerste sign-in
De allereerste tool-call doorloopt de device code flow. U ziet iets als:
To sign in, use a web browser to open https://microsoft.com/devicelogin
and enter the code ABCD-1234 to authenticate.Open de URL, plak de code, log in met het Azure-account dat BC-permissies heeft. Uw token wordt dan lokaal gecached (via msal-extensions met platform-specifieke secure storage — DPAPI op Windows, Keychain op macOS, libsecret op Linux). Volgende runs zijn niet-interactief tot vervaldatum — waarna de proxy stilletjes refresht.
Eerste test: vraag uw AI
Herstart uw AI-client en probeer één van deze:
- “Toon mij de top 5 klanten in CRONUS USA.”
- “Welke leveranciers hebben een openstaand saldo boven €5.000?”
- “Lijst Sales Invoices van vorige maand met status Open.”
In Static mode kiest de AI de tool direct (bv. ListCustomers_PAG30009) met parameters zoals top: 5. In Dynamic mode ziet u drie stappen vuren — bc_actions_search → bc_actions_describe → bc_actions_invoke. Beide modes geven dezelfde data terug.
Krijgt u een echt antwoord, dan bent u klaar. Zo niet — ga naar Troubleshooting hieronder.
Wat erna komt — wanneer BC MCP het begin is, niet het einde
BC MCP is de snelste manier om te zien of AI-agents bij uw bedrijf passen — gratis, open-source, op een namiddag operationeel. De meeste van onze kleine-bedrijfsklanten stellen al snel de volgende vraag: “En de rest van onze systemen?”
Dezelfde MCP-plumbing strekt zich uit naar al de rest — CAD-bibliotheken, ERPs, custom databases, interne tools. De Fusion 360 case study is één voorbeeld van hoe dat er in de praktijk uitziet: parametrische CAD-bron → brand-aware A4 spec sheet, end-to-end via MCP in ~28 seconden.
Bekijk de Fusion 360 case study →
Twee weken, vaste scope, op maat per systeem. Wij doen, u kijkt.
Static vs Dynamic Tool Mode
| Static | Dynamic | |
|---|---|---|
| Tools die de AI ziet | Eén per geselecteerde pagina (bv. 10 tools) | Drie generieke tools |
| Performance eerste call | Snel (sub-seconde) | Traag op eerste call (50–60s als Discover Additional Objects aanstaat) |
| Volgende calls | Snel | Snel — de catalog is gecached |
| AI prompt cost | Hoger (de AI ziet alle tool-schemas) | Lager (slechts drie meta-tools) |
| Best voor | Een afgebakende, expliciete set use cases | Flexibele exploratie over veel pagina’s |
Onze aanbeveling: start met Static mode voor uw eerste test (snelle feedback, u weet exact welke tools bestaan). Schakel over naar Dynamic zodra uw gebruikers dingen beginnen te vragen waarvoor u geen tool had voorgeselecteerd.
BC-versie compatibiliteit
Microsoft veranderde de MCP-endpoint-vorm in BC v28 en documenteert nu enkel de v28-host voor non-Microsoft MCP-clients. De proxy detecteert welke host u opgeeft en past URL-vorm, request-headers en OAuth-scope automatisch aan:
| BC-versie | BC_BASE_URL | URL-vorm | Routing-headers | OAuth-scope |
|---|---|---|---|---|
| 28+ (default) | https://mcp.businesscentral.dynamics.com | bare host, geen path | TenantId + EnvironmentName (plus Company, ConfigurationName) | https://mcp.businesscentral.dynamics.com/.default |
| 26 / 27 | https://api.businesscentral.dynamics.com | /v2.0/{environment}/mcp toegevoegd | Company, ConfigurationName | https://api.businesscentral.dynamics.com/.default |
Wisselen is een single-line change in .env of via --BaseUrl; de scope en headers volgen automatisch. Stel BC_TOKEN_SCOPE enkel in als u de auto-pick wilt overschrijven.
Cold-start mitigation
BC’s MCP-endpoint kan 30s+ nodig hebben om de allereerste tools/list-call te beantwoorden nadat de omgeving idle stond — langer dan Claude Desktop’s hardcoded MCP-request-timeout. De proxy maskeert dit met een drie-laagse cache: bij startup laadt hij de eerder gecachete tools-lijst van disk (per tenant/environment/company/configuration), pre-warmt tools/list zodra de upstream-sessie verbindt, en beantwoordt de stdio-handler vanuit een in-memory cache met 5-minuut TTL in plaats van bij elke call naar BC te round-trippen.
De allereerste install op een vers cold-started BC-omgeving kan nog steeds éénmalig de 30s-timeout raken — er is dan nog geen disk-cache. Elke volgende launch is instant.
Configuration parameters
Volledige set opties:
| Parameter | CLI-argument | Env-var | Default |
|---|---|---|---|
| Tenant ID | --TenantId | BC_TENANT_ID | vereist |
| Client ID | --ClientId | BC_CLIENT_ID | vereist |
| Environment | --Environment | BC_ENVIRONMENT | Production |
| Company | --Company | BC_COMPANY | vereist |
| Configuration Name | --ConfigurationName | BC_CONFIGURATION_NAME | unset |
| Custom Auth Header | --CustomAuthHeader | BC_CUSTOM_AUTH_HEADER | unset (slaat device flow over indien meegegeven) |
| Base URL | --BaseUrl | BC_BASE_URL | https://mcp.businesscentral.dynamics.com (BC v28) |
| Token Scope | --TokenScope | BC_TOKEN_SCOPE | auto-gekozen op basis van base URL host (zet enkel om te overriden) |
| 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 | uit |
Token cache locaties (wanneer geen custom auth header is meegegeven):
- 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 de configuration in BC en verifieer dat de Active toggle aan staat. De pagina bewaren zet Active niet automatisch aan. Dezelfde foutmelding kan ook komen wanneer de ConfigurationName-headerwaarde verschilt van het BC-record met zelfs één trailing space.
Authenticatie-fouten. Verifieer het redirect-URL-formaat (ms-appx-web://Microsoft.AAD.BrokerPlugin/<clientID>) en dat “Allow public client flows” is ingeschakeld op de Azure app registration. Zorg dat alle API-permissies zijn toegekend en admin-consented. Run setup opnieuw als de device flow timed out.
Calls hangen of timen out (vooral in Dynamic Tool Mode). De eerste bc_actions_search op een configuration met Discover Additional Objects enabled enumereert de hele metadata-catalog — gemeten op 50–60s server-side op een Cronus demo. Verhoog BC_HTTP_TIMEOUT_SECONDS (default 120) als u httpx.ReadTimeout ziet op de eerste call. Volgende calls binnen dezelfde sessie zijn typisch sub-seconde; de cold-start cache van de proxy houdt tools/list instant op elke volgende launch.
JSON-RPC -32603 "An error occurred." zonder detail. Dit is BC’s catch-all wanneer er iets binnen een Dynamic-tool-call misgaat. De echte reden wordt gelogd naar Azure Application Insights als event RT0054 met custom dimension toolInvocationFailureReason. Zet telemetry aan op de BC-omgeving en query:
traces
| where customDimensions.eventId == 'RT0054'
| where customDimensions.toolInvocationResult == 'Failure'Frequente reconnects in logs. Inspecteer upstream availability — de proxy logt Upstream connection error (...); reconnecting in Xs (attempt N/M) bij elke retry. Na het geconfigureerde budget geeft de proxy op en sluit de lokale stdio-pipe.
Herhaalde sign-in prompts. De MSAL token cache is mogelijk niet schrijfbaar. Geef --DeviceCacheLocation mee om naar een directory te wijzen die u zelf controleert.
No module named bc_mcp_proxy. Installeer de distributie in dezelfde Python-interpreter waar uw MCP-client mee start — python -m pip install --upgrade 360solutions-bc-mcp.
Security model
- Geen application secrets. Enkel delegated permissions via de device-code flow. Geen client secret om te beheren of te roteren.
- Tokens lokaal gecached met OS-specifieke secure storage (DPAPI op Windows, Keychain op macOS, libsecret op Linux). Geen plaintext op disk.
- Geen tokens in logs. De proxy logt nooit access- of refresh-tokens; debug-output bevat enkel expiry-timestamps voor diagnose.
- Permissies zijn delegated. Wat de proxy kan zien en doen, kan de ingelogde gebruiker al manueel in BC. De AI krijgt geen extra rechten.
- Configuration name als gate. In BC bepaalt u per MCP Configuration welke pagina’s en objecten zijn blootgesteld. Plaats gevoelige data achter een aparte configuration die u alleen Active zet voor specifieke gebruikers.
Hulp nodig?
De Azure App Registration vraagt aandacht voor detail. Voor klanten die liever niet zelf met Manifest.json, redirect URI’s en delegated permissions worstelen, biedt 360 Solutions een end-to-end hands-on Setup Session — gratis tot 30 juni 2026 (60–90 min):
- Azure App Registration aangemaakt en gevalideerd in uw tenant
- BC MCP Configuration aangemaakt op de juiste omgeving(en)
- Proxy plus AI-client (Claude Desktop, VS Code of Cursor) geïnstalleerd en getest op uw werkstation
- Korte gebruikerstraining: welke vragen werken goed, welke niet, wat zijn de privacy- en kost-trade-offs
- Optioneel: Application Insights telemetry-aansluiting zodat u later kunt zien wie welke tools gebruikt
Boek eerst een gratis 30-min ontdekkingsgesprek om te zien of het past — geen verplichting.
📦 360solutions-bc-mcp op GitHub · MIT-licentie
📧 dev@360solutions.be