Overview

This MCP (Model Context Protocol) server lets AI assistants access Microsoft Dynamics 365 Business Central data by translating MCP v2.0 tool calls into correctly formatted Business Central REST API requests. It is intended for developer workflows where an LLM-based agent (for example in Claude Desktop, Claude Code, or any MCP-capable client) needs to read or modify Business Central records — customers, items, sales orders, ledgers, etc. The server handles URL formatting, authentication, and CRUD semantics so agents can call human-readable tools like get_schema or list_items without worrying about Business Central API quirks.

Key benefits: zero-install deployment via npx for quick experimentation, support for Azure CLI interactive auth (recommended) and client_credentials service-to-service auth, and a small, predictable set of tool names designed for direct LLM integration.

Features

Correct Business Central API URL formatting: uses /companies({id})/{resource} (no ODataV4 segment)
Zero-install run via npx (or install locally for development)
Two authentication modes: azure_cli (recommended) and client_credentials
Clean, short tool names (get_schema, list_items, get_item, create_item, update_item, delete_item)
Full CRUD support for Business Central records
Designed to be used as an MCP v2.0 server for LLM agents

Installation / Configuration

Recommended: run directly with npx from an MCP-capable client (example JSON for Claude-style MCP config):

{
  "mcpServers": {
    "business-central": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@knowall-ai/mcp-business-central"],
      "env": {
        "BC_URL_SERVER": "https://api.businesscentral.dynamics.com/v2.0/{tenant-id}/{environment}/api/v2.0",
        "BC_COMPANY": "Your Company Display Name",
        "BC_AUTH_TYPE": "azure_cli"
      }
    }
  }
}

Notes:

On Windows, wrap npx with cmd /c as shown.
Replace {tenant-id} and {environment} (e.g., Production or Sandbox).

Local development:

git clone https://github.com/knowall-ai/mcp-business-central.git
cd mcp-business-central
npm install
npm run build
node build/index.js

Environment variables

Variable	Required	Purpose	Example
BC_URL_SERVER	Yes	Base Business Central API URL	https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0
BC_COMPANY	Yes	Company display name to target	“Contoso Ltd”
BC_AUTH_TYPE	No	Auth mode: azure_cli (default) or client_credentials	azure_cli
BC_TENANT_ID	If client_credentials	Azure AD tenant GUID	00000000-0000-0000-0000-000000000000
BC_CLIENT_ID	If client_credentials	App registration client ID	00000000-0000-0000-0000-000000000000
BC_CLIENT_SECRET	If client_credentials	App secret value	your-secret-value

Example API base URL:

https://api.businesscentral.dynamics.com/v2.0/00000000-0000-0000-0000-000000000000/Production/api/v2.0

Authentication

Azure CLI (recommended)

Use your existing Azure CLI login: install Azure CLI and run az login.
Verify token acquisition: az account get-access-token --resource https://api.businesscentral.dynamics.com
Set BC_AUTH_TYPE=azure_cli; the server will call Azure CLI to obtain access tokens.

Client credentials (service-to-service)

Create an Azure app registration (single tenant), add Application permission for Dynamics 365 Business Central (app_access), and grant admin consent.
Create a client secret and record BC_TENANT_ID, BC_CLIENT_ID, BC_CLIENT_SECRET.
In Business Central, register the app via “Microsoft Entra Applications” to create an application user and assign permission sets (e.g., D365 BUS FULL ACCESS).
This flow is more complex and has platform-specific pitfalls; consult the server’s troubleshooting docs when needed.

Available Tools / Resources

The server exposes a concise set of MCP tools (tool names are the ones LLMs will call):

Tool	Purpose
get_schema	Retrieve metadata/schema for a resource (fields, types)
list_items	List records from a resource (supports filters/pagination)
get_item	Get a single record by id
create_item	Create a new record
update_item	Update an existing record (by id)
delete_item	Delete a record (by id)

Example: the server will translate list_items for customers into:

GET {BC_URL_SERVER}/companies({companyId})/customers?$filter=...

(Important: the path uses /companies(id)/resource and not an ODataV4 prefix.)

Use Cases (concrete examples)

Fetch customer list for an LLM-powered assistant: call list_items resource=customers filter=“balance gt 0” to surface overdue customers for an agent that drafts collection emails.
Create a sales order draft: agent gathers order data from user and calls create_item on salesOrders with line items — server handles record creation and returns the new ID.
Sync product catalog: a background agent calls list_items on items to export SKU, price and inventory into another system.
Generate quick reports: agent calls get_schema and list_items to produce a CSV of customers with open balances and recent activity.
Automated reconciliations: scheduled agent uses client_credentials auth to read ledgers and flag mismatches.

Tips & Troubleshooting

Prefer azure_cli for quick setup and fewer platform-specific permissions issues.
Ensure BC_COMPANY exactly matches the display name in Business Central (server matches name to company ID).
If client_credentials is used, verify the application user appears in Business Central users and has sufficient permission sets.
If you see unexpected 401/403 responses, verify the Azure token audience is https://api.businesscentral.dynamics.com and that admin consent was granted.

For development, run locally and inspect logs to see the exact Business Central HTTP requests the MCP server issues — this helps when adjusting permissions or URL formats.

For full troubleshooting steps and edge cases around application users, consult the project docs in the repository.

Microsoft Dynamics 365 Business Central MCP Server