Business Central MCP Server
Model Context Protocol server for Microsoft Dynamics 365 Business Central.
> Connect AI agents to Business Central data — from a single npx command for developers to a full Azure deployment for enterprise.
Two Ways to Use
| npm (Developer) | Azure (Enterprise) | |
|---|---|---|
| Use case | Local AI assistants, development, prototyping | Production cloud services, multi-tenant |
| Transport | stdio (stdin/stdout) | HTTP/SSE |
| Clients | Claude Desktop, Claude Code, Cline, Cursor | Claude.ai, Copilot Studio, Azure AI Foundry |
| Setup time | 2 minutes | 15 minutes |
| Infrastructure | None (runs locally) | Azure Container Apps |
Quick Start: npm (Developer Mode)
Option A: npx (no install)```bash
npx business-central-mcp-server --stdio
### Option B: Global install```bash
npm install -g business-central-mcp-server
business-central-mcp-server --stdio
Configure in Claude Desktop
Add to your claude_desktop_config.json:```json
{
"mcpServers": {
"business-central": {
"command": "npx",
"args": ["-y", "business-central-mcp-server", "--stdio"],
"env": {
"BC_TENANT_ID": "<your-tenant-id>",
"BC_CLIENT_ID": "<your-client-id>",
"BC_CLIENT_SECRET": "<your-client-secret>",
"BC_ENVIRONMENT_NAME": "Sandbox",
"BC_COMPANY_ID": "<your-company-id>"
}
}
}
}
### Configure in Claude Code
Create `.mcp.json` in your project root:```json
{
"mcpServers": {
"business-central": {
"command": "npx",
"args": ["-y", "business-central-mcp-server", "--stdio"],
"env": {
"BC_TENANT_ID": "<your-tenant-id>",
"BC_CLIENT_ID": "<your-client-id>",
"BC_CLIENT_SECRET": "<your-client-secret>",
"BC_ENVIRONMENT_NAME": "Sandbox",
"BC_COMPANY_ID": "<your-company-id>"
}
}
}
}
CLI Arguments
You can pass configuration as CLI arguments instead of environment variables:```bash
business-central-mcp-server --stdio \
--tenantId <tenant-id> \
--clientId <client-id> \
--clientSecret <client-secret> \
--environment Sandbox \
--companyId <company-id>
### Getting Your Credentials
1. **Azure AD App Registration** — Register an app in Azure Portal > App registrations
2. **API Permissions** — Add `Dynamics 365 Business Central > API.ReadWrite.All` (Application permission)
3. **Client Secret** — Create under Certificates & secrets
4. **Tenant ID** — Found on the app registration Overview page
5. **Company ID** — Use the `list_companies` tool after connecting, or find it in BC Admin Center
---
## Quick Start: Azure (Enterprise Mode)
For production deployments serving cloud AI clients (Claude.ai, Copilot Studio, Azure AI Foundry).
### Prerequisites
- Azure subscription
- Business Central tenant with API access
- Azure AD app registration (see Deployment Guide)
### Deploy
Use the GitHub Actions workflow or deploy manually:```bash
git clone https://github.com/olederkach/business-central-mcp-server.git
cd business-central-mcp-server
# Deploy to Azure Container Apps (see docs/DEPLOYMENT.md for full walkthrough)
What gets deployed:
- Azure Container App (auto-scaling, 1-10 replicas)
- Azure Container Registry
- Application Insights (telemetry, optional)
Authentication Modes
| Mode | Server AUTH_MODE |
Use Case |
|---|---|---|
| OAuth | oauth |
Claude.ai, Copilot Studio (user-level auth) |
| API Key | api-key |
Azure AI Foundry, simple integrations |
Connect Claude.ai (OAuth)```
Claude.ai > Settings > MCP Servers > Add Custom
Name: Business Central
URL: https://<your-server>.azurecontainerapps.io/mcp
Client ID: <your-azure-client-id>
Client Secret: <your-azure-client-secret>
### Connect Copilot Studio (OAuth Dynamic Discovery)```
Copilot Studio > Knowledge > Add knowledge > MCP
Name: BC-MCP-Server
URL: https://<your-server>.azurecontainerapps.io/mcp
Auth: OAuth 2.0 > Dynamic discovery
Client ID: <your-azure-client-id>
Client Secret: <your-azure-client-secret>
Scope: api://<your-azure-client-id>/.default openid
Connect Azure AI Foundry (API Key)```
Settings > Connections > + New connection > MCP
Endpoint: https://<your-server>.azurecontainerapps.io/mcp
Authentication: API Key (X-API-Key header)
See docs/DEPLOYMENT.md for the complete deployment guide and docs/MCP_CLIENT_SETUP.md for all client configurations.
---
## Tools (14)
### API Context Management
| Tool | Description | Type |
|------|-------------|------|
| `list_bc_api_contexts` | Discover available API routes | read-only |
| `set_active_api` | Switch publisher/group/version | state change |
| `get_active_api` | Get current API context | read-only |
### Company Management
| Tool | Description | Type |
|------|-------------|------|
| `list_companies` | List all BC companies | read-only |
| `set_active_company` | Switch active company | state change |
| `get_active_company` | Get current company | read-only |
### Resource Discovery
| Tool | Description | Type |
|------|-------------|------|
| `list_resources` | List all entity names | read-only |
| `get_odata_metadata` | Search OData schema | read-only |
| `get_resource_schema` | Get entity fields & types | read-only |
### CRUD Operations
| Tool | Description | Type |
|------|-------------|------|
| `list_records` | Query with OData filter/sort/page | read-only |
| `create_record` | Create new record | destructive |
| `update_record` | Patch existing record (ETag support) | destructive |
| `delete_record` | Permanently remove record | destructive |
| `find_records_by_field` | Search by field value | read-only |
### Example```
User: "Show me customers in Atlanta"
Tool call: list_records
Arguments: { "resource": "customers", "filter": "city eq 'Atlanta'", "top": 10 }
Multi-API Support
Business Central exposes multiple API surfaces. This server supports all of them:
- Standard BC API v2.0 — customers, vendors, items, salesOrders, etc.
- Microsoft Extended APIs — automation, analytics
- Custom ISV APIs — third-party extension APIs
Switch at runtime:```
set_active_api({ publisher: "microsoft", group: "automation", version: "v1.0" })
---
## Configuration
### Environment Variables
#### Required (both modes)
| Variable | Description |
|----------|-------------|
| `BC_TENANT_ID` | Azure AD tenant GUID |
| `BC_CLIENT_ID` | App registration client ID |
| `BC_CLIENT_SECRET` | App registration client secret |
| `BC_ENVIRONMENT_NAME` | `Sandbox` or `Production` |
#### Recommended
| Variable | Default | Description |
|----------|---------|-------------|
| `BC_COMPANY_ID` | *(auto-discovered)* | Default company UUID |
#### Enterprise (HTTP mode only)
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_API_KEYS` | — | Comma-separated API keys for client auth |
| `AUTH_MODE` | `api-key` | `api-key` or `oauth` |
| `CORS_ORIGINS` | `*` | Allowed origins |
| `PORT` | `3005` | HTTP port |
| `KEY_VAULT_NAME` | — | Azure Key Vault for secrets |
| `APPLICATIONINSIGHTS_CONNECTION_STRING` | — | Monitoring |
| `RATE_LIMIT_ENABLED` | `true` | Enable rate limiting |
See .env.example for the complete reference.
---
## Architecture```
┌──────────────────────────────┐
│ AI Clients │
│ Claude Desktop/Code (stdio) │
│ Copilot Studio (HTTP) │
│ Azure AI Foundry (HTTP) │
└──────────┬───────────────────┘
│
┌────────────────┼────────────────┐
│ stdio │ │ HTTP/SSE
▼ │ ▼
┌─────────────────┐ │ ┌─────────────────────────┐
│ stdio-server │ │ │ Express + MCP Protocol │
│ (npm/npx) │ │ │ (Azure Container Apps) │
│ │ │ │ │
│ 14 Generic │ │ │ API Key / OAuth Auth │
│ Tools │ │ │ Rate Limiting │
└────────┬────────┘ │ │ App Insights │
│ │ └───────────┬──────────────┘
│ │ │
└────────────────┼────────────────┘
│
▼
┌──────────────────────────────┐
│ Business Central API │
│ OAuth 2.0 (client_credentials)│
│ OData V4.0 │
└──────────────────────────────┘
Key Components
| Component | npm Mode | Enterprise Mode |
|---|---|---|
| Transport | stdio (stdin/stdout) | HTTP + SSE |
| Tools | 14 generic tools | 14 generic + entity-specific |
| Auth (BC) | OAuth client_credentials | OAuth client_credentials |
| Auth (clients) | N/A (local process) | API Key or OAuth |
| State | In-process (session map) | Per-request |
| Monitoring | stderr logs | Application Insights |
| Secrets | env vars / CLI args | Azure Key Vault |
Development
Local Setup```bash
git clone https://github.com/olederkach/business-central-mcp-server.git
cd business-central-mcp-server
npm install
Configure
cp .env.example .env
Edit .env with your BC credentials
Development (stdio)
npm run dev:stdio
Development (HTTP)
npm run dev:http
Production build
npm run build
npm start
### Build & Pack```bash
npm run build # Compile TypeScript
npm pack # Create .tgz for local install
npm link # Symlink for local development
Project Structure```
src/
├── index.ts # Entry point (stdio/HTTP dispatcher)
├── version.ts # Centralized version constant
├── config.ts # CLI args + env var parsing
├── server.ts # Express HTTP server
├── api/ # API context & company management
├── auth/ # Authentication (OAuth, API Key, DCR)
├── bc/ # Business Central client & metadata
├── config/ # Environment validation
├── errors/ # Error codes & builders
├── mcp/ # MCP protocol handler & prompts
├── middleware/ # Express middleware
├── monitoring/ # App Insights & analytics
├── openapi/ # OpenAPI spec generation
├── tools/ # Tool definitions & executors
│ ├── generic-tools.ts # 14 generic tool definitions
│ ├── generic-executor.ts # Generic tool executor
│ ├── executor.ts # Entity-specific executor (HTTP mode)
│ └── generator.ts # Tool generator from metadata
├── transports/ # stdio, SSE, Copilot SSE servers
└── utils/ # Logger, validators, sanitizer
```
Troubleshooting
"No tools available" in Copilot Studio UI
Expected with MCP protocol 2024-11-05. Tools work at runtime — test from the chat interface.
"Authentication failed"
- npm mode: Verify
BC_CLIENT_ID,BC_CLIENT_SECRET, andBC_TENANT_ID - Enterprise: Also check
MCP_API_KEYSandX-API-Keyheader
"Cannot connect to Business Central"
- Verify Azure AD app registration has
Dynamics 365 Business Central > API.ReadWrite.All - Confirm the app has admin consent granted
- Test the credentials directly:
bash curl -X POST "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \ -d "client_id=<client-id>&client_secret=<secret>&scope=https://api.businesscentral.dynamics.com/.default&grant_type=client_credentials"
"Company not found"
Run list_companies first to get available company IDs, then use set_active_company or set BC_COMPANY_ID.
Documentation
| Document | Description |
|---|---|
| DEPLOYMENT.md | Azure deployment guide |
| QUICK_START.md | 5-minute quick start |
| Copilot Studio Setup | Copilot Studio integration |
| Azure AI Foundry | Azure AI Foundry setup |
| API Reference | OData parameters, errors, limits |
| Architecture | ADRs and design decisions |
| SECURITY.md | Security policies |
| CHANGELOG.md | Version history |
License
MIT — see LICENSE
Links
- MCP Protocol Specification
- BC API Documentation
- Azure Container Apps
Built for the Business Central and AI community.
