tools/call over
POST /business-central/mcp. The connector reads Microsoft Dynamics 365 Business
Central online and is connected through OAuth with a Microsoft work or school
account (see Forbind Business Central). Your
organization needs access to Business Central (a subscription, or a plan that
covers it, see What decides access),
and your user must hold a seat or plan licence (assigned under Team in the
portal, see Team).
The connector is in early access. It currently serves five tools: three discovery tools
(
list_environments, list_companies, get_company_information) and a generic,
allow-listed query tool (query_entity) with its companion
(list_entity_metadata). The Business Central description in the portal’s
Marketplace also lists tools that are not available yet. This page documents only
what is served today.Endpoint:
https://mcp.consile.ai/business-central/mcp. Business Central is its
own named connector with only its own tools. Tool names are namespaced
business-central__<tool> (e.g. business-central__list_companies); the bare
names are used below for readability. A bare name in a request returns
Unknown tool.The connector is multi-instance: one instance covers one Microsoft Entra
tenant, including all of its environments and companies. An administrator adds
further connections (agreements, aftaler, in the portal), each served at its
own endpoint, e.g. https://mcp.consile.ai/business-central-2/mcp, with tools
named business-central-2__<tool>. An agreement can hold another tenant, or the
same tenant locked to another company.tools/list returns
the five business-central__* tools plus the unprefixed system tool
connect_account. Without access only
connect_account is listed, and the initialize result includes instructions
explaining how to get access. A user without a seat still sees the tools, but every
call is refused. Every tool has a title and the annotations readOnlyHint: true,
destructiveHint: false and openWorldHint: false. A successful result contains
the payload twice: as JSON text in content and as the same object in
structuredContent. The examples below show that payload.
Authorization and read-only enforcement
The account is connected through Microsoft’s OAuth sign-in. Only work or school accounts can connect; Microsoft refuses a personal Microsoft account. The requested permissions are:https://api.businesscentral.dynamics.com/Financials.ReadWrite.Alloffline_access(keeps the connection alive)
- The connector has no write tools.
- Consile sends only read requests to the Business Central API.
- The connect is rejected if Microsoft’s grant contains permissions beyond the
Business Central API,
offline_accessand the standard sign-in scopes (openid,profile,email).
Shared conventions
Environments and companies
Business Central addresses data by an environment name (a Production or Sandbox environment in the tenant) and a company id (a legal entity inside that environment). Unless an administrator has locked the connection, both are per-call arguments and no company is stored. The intended order islist_environments (only when the default is wrong), then list_companies, then
the company-scoped tools with the GUID in hand.
Business Central environment name, 1 to 80 characters. Optional on every tool that
takes it. Call
list_environments if the tenant uses
another name. An unknown name returns an error. It names the environment the
connection serves when the credential reaches only one; otherwise it points to
list_environments (see Errors).The company id from
list_companies. Required on
get_company_information and query_entity. It cannot be derived from a company
name. A wrong GUID returns a 404 error, not another company’s data.Optional case-insensitive substring filter (
list_companies and
list_entity_metadata). At least one character. Refused on list_companies on a
locked connection.Result context
Every result exceptlist_environments echoes a context object with the
environment (and the companyId, where one applies) it was read from, so a result
cannot be misattributed to another company. @odata.* annotation keys are removed
from every row.
Typical call order
list_companies(andlist_environmentsonly if the environment is notProduction).get_company_information, to confirm which books are being read.list_entity_metadata, to see which entity sets the environment serves (not on a locked connection).query_entitywithselectandfilter.
list_environments
Lists the Business Central environments in the connected Microsoft Entra tenant. Only Business Central environments are returned. Call it only when the tenant runs several environments or a tool reported an unknown environment name. On a locked connection it returns only the locked environment. Arguments: none.Each item has
name, type (Production or Sandbox), countryCode and
aadTenantId (the Entra tenant id). A missing countryCode or aadTenantId
is null.list_companies
Lists the companies (legal entities) in an environment, with the GUID every company-scoped tool requires. On a locked connection it returns only the locked company in the locked environment, refusessearch and leaves out
ambiguous.
true when a search matched more than one company. Ask the user which one is
meant instead of guessing.get_company_information
Reads a company’s own master data: registered name, address, VAT registration number (the CVR number in Denmark), currency code and the start of the current fiscal year. Use it to confirm which books you are reading before reporting numbers.The company’s
companyInformation record as Business Central returns it (for
example displayName, addressLine1, city, postalCode, country,
taxRegistrationNumber, currencyCode, currentFiscalYearStartDate), or null
if the company has none.list_entity_metadata
Lists the entity sets an environment exposes. Use thename values as the entity
argument of query_entity.
It is environment-level, so it takes no companyId: the same sets are served inside
every company of that environment. It is not available on a
locked connection; use the
allow-listed entity sets there.
Each item has
name, kind, url and queryable. queryable: false means the
set exists in the environment but is outside the allow-list query_entity accepts
(for example companies, or a custom API page), so it cannot be read here.search to narrow it.
query_entity
Reads one entity set of the standard Business Central API v2.0 with OData options, one page at a time, or one record by id. Only the 85 allow-listed entity sets can be read (see the list below).Entity set name, 1 to 80 characters, letters and digits only (e.g.
customers,
salesInvoices, generalLedgerEntries). Matched case-insensitively against the
allow-list. A name with any other character, or one outside the allow-list, is
refused; an unknown name is answered with up to five closest matches.Reads one record instead of a page.
filter, orderby and pageSize do not
apply; select and expand do.Raw OData
$filter expression, 1 to 1,000 characters. String literals are
single-quoted, with an embedded single quote doubled
(displayName eq 'O''Brien'). Dates are written unquoted as YYYY-MM-DD
(postingDate ge 2026-01-01); a quoted date is rejected by Business Central.Field names for
$select. Always pass it: Business Central rows are wide, and a
page of full rows is likely to exceed the size cap.$expand expression, 1 to 500 characters (e.g. dimensionSetLines). It
multiplies the result size, so use it sparingly.Opaque continuation token from a previous result’s
nextCursor. Omit it for the
first page and never construct or edit one. Refused on a
locked connection.Token for the next page, or
null when the collection is exhausted. hasMore is
true when a next page exists. There is no total count.Paging
nextCursor is opaque. To read the next page, pass it back unchanged as cursor,
together with the same environment, entity and companyId as the first call.
The cursor continues the same query. A cursor is only accepted with the
companyId of the call that produced it; with another companyId it is refused
with Invalid cursor: it is not a continuation token from a previous call on this connection. Start the listing again without a cursor. The environment argument is
not checked on a continuation.
On a locked connection cursor is refused and nextCursor is not
returned, so paging is not possible. hasMore still tells you whether more rows
exist: narrow filter, or raise pageSize (at most 500) and keep select
small so the page stays under the size cap.
Size cap
A result larger than 100,000 JSON characters is refused, and the client sees onlyTool invocation failed. Narrow select, add a filter or lower pageSize.
Allow-listed entity sets
All 85 entity sets query_entity accepts
All 85 entity sets query_entity accepts
accounts, accountingPeriods, agedAccountsPayable, agedAccountsReceivable,
applyVendorEntries, approvalEntries, approvalUserSetups, attachments,
balanceSheets, bankAccounts, cashFlowStatements, companyInformation,
contacts, contactsInformation, countriesRegions, currencies,
currencyExchangeRates, customers, customerContacts,
customerFinancialDetails, customerPaymentJournals, customerPayments,
customerReturnReasons, customerSales, defaultDimensions, dimensions,
dimensionSetLines, dimensionValues, disputeStatus, documentAttachments,
employees, fixedAssets, fixedAssetLocations, generalLedgerEntries,
generalLedgerSetup, generalProductPostingGroups, incomeStatements,
inventoryPostingGroups, items, itemCategories, itemLedgerEntries,
itemVariants, jobQueueEntries, jobQueueLogEntries, journals,
journalLines, locations, opportunities, paymentMethods, paymentTerms,
pictures, postedApprovalEntries, projects, purchaseCreditMemos,
purchaseCreditMemoLines, purchaseInvoices, purchaseInvoiceLines,
purchaseOrders, purchaseOrderLines, purchaseReceipts,
purchaseReceiptLines, retainedEarningsStatements, salesCreditMemos,
salesCreditMemoLines, salesInvoices, salesInvoiceLines, salesOrders,
salesOrderLines, salesQuotes, salesQuoteLines, salesShipments,
salesShipmentLines, salespersonsPurchasers, shipmentMethods,
subscriptions, taxAreas, taxGroups, timeRegistrationEntries,
trialBalances, unitsOfMeasure, vendors, vendorPayments,
vendorPaymentJournals, vendorPurchases, workflowApprovers.companies is deliberately not on the list; use list_companies. A listed set can
still be missing in a given environment, depending on localisation and version.
list_entity_metadata shows what the environment actually serves. Custom API pages
and extension APIs cannot be read.
connect_account
connect_account is a system tool that the Business Central endpoint lists next to
the five tools. It takes no arguments and its name has no business-central__
prefix. It returns { "connect_url": "…", "instructions": "…" }. The user opens
connect_url in a browser and is sent to Microsoft to sign in and approve access.
The link expires after 10 minutes. It only works for accounts that subscribe to
Business Central and for users who have accepted Consile’s terms in the portal.
Use it to reconnect after the access expired or was removed: completing the link
connects the account again with the new Microsoft sign-in.
Request
Company lock
An administrator can lock a Business Central connection to one environment and one company in it, in the portal (see Lås en forbindelse til én virksomhed). The lock is optional and belongs to one endpoint:business-central and business-central-2 each have their
own. On a connection without a lock, nothing in this section applies.
On a locked connection:
list_environmentsreturns only the locked environment, andlist_companiesreturns only the locked company, withcountset to1.list_companiesreads the locked environment, refusessearchand leaves outambiguous.get_company_informationandquery_entityget the locked environment filled in when you leaveenvironmentout. Becauseenvironmentdefaults toProduction, passingProductioncounts as leaving it out; the result’scontextnames the environment that was read. Naming another environment is refused.companyIdis still required, and it must be the locked company. A call that names another company is refused.query_entityrefusescursorand does not returnnextCursor. See Paging.list_entity_metadatacannot be limited to one company.tools/listleaves it out, and a direct call is refused. The other four tools remain.- After a reconnect, until an administrator has chosen the environment and company
again,
tools/listreturns all five tools and every call is refused. connect_accountis not affected.
isError: true. <label> is the company
name the administrator chose, <environment> and <companyId> are the locked
values, and <tool> is the bare tool name.
If the locked environment no longer exists,
list_companies,
get_company_information and query_entity return the connector’s own
Environment '<name>' not found text (see Errors).
A company can be locked on only one connection at a time. A production company and
its sandbox copy with the same id count as the same company. Automatic renewal of
the Microsoft access does not affect the lock. When an administrator disconnects the
connection, the lock is removed.
Errors
Tool failures come back as a normaltools/call result with isError: true and one
text block, not as a JSON-RPC error. The connector returns explanatory messages for
the common failures:
Limits
- Business Central’s own budget: Microsoft allows 6,000 requests per 5 minutes
per Business Central user, shared with every other Business Central client of that
user. Narrow the
filterinstead of paging through everything. - Page size: default 50, maximum 500 rows.
- Result size: 100,000 JSON characters for
query_entity, 40,000 forlist_entity_metadata.
429 (JSON-RPC error -32029, Retry-After: 1)
instead of a tool result. See Errors & limits for
the current limits and the protocol-level errors shared by all connectors.