How to Set Up the Business Central MCP Server and Run Data Queries Without an API Page

Introduction

If your business runs on Microsoft Dynamics 365 Business Central, you have probably tried asking an AI agent a question about your own data. Out of the box, the agent could read customers, items, sales documents, and G/L entries. Anything else meant a developer had to write an AL extension and deploy it before the agent could answer. This tutorial walks through the 2026 wave 2 change that removes that step: the Business Central MCP server now offers Data Query Tools, so an agent writes, validates, and runs its own read-only query against any table the signed-in user is allowed to see. You will enable the feature on the MCP Server Configurations page, connect a client such as Copilot Studio or VS Code, run a first agent-composed query, and review the permission and audit implications.

Quick answer

Enable Data Query Tools (Preview) on an MCP server configuration in Business Central update 29.0, connect your MCP client to https://mcp.businesscentral.dynamics.com, and the agent composes AL queries against any table your user account can see.

Evidence

Two numbers anchor this tutorial. First, Microsoft lists the feature as Run data queries with MCP Server in the update 29.0 what’s new table under Copilot and agents, roadmap ID 573312, with the Microsoft 365 roadmap entry giving status launched, general availability October CY2026, worldwide standard multi-tenant, as of October 2026. Second, the Business Central MCP server overview exists because there is a concrete client limit to design around: the configuration guide notes Copilot Studio currently limits an agent to 70 tools, which is exactly why Dynamic Tool Mode exists for configurations that expose the full standard API catalog.

Microsoft describes the capability in one sentence: “Use new MCP tools to define, validate, and run custom data queries. This allows your MCP application to query data for which no existing APIs are available.” The overview page adds the framing that matters for architects: “The Business Central MCP server enables AI clients to interact with Business Central environments from various channels such as Visual Studio Code, Copilot Studio, and other MCP-compliant clients, allowing customers and employees to conversationally work with Business Central data and business logic.”

The context is the 2026 wave 2 release of Business Central, version 29.0, where the MCP server gained this database-level query ability on top of the API-page model it shipped with in the 2025 wave 2 release. Microsoft also retired the twice-yearly release wave announcements in September 2026, moving to continuous roadmap publishing, so expect future capabilities like this to land as roadmap items rather than waiting for a wave.

Prerequisites

• Business Central online on update 29.0 (2026 wave 2) or later. The MCP server applies to Business Central online only.
• An admin account with the MCP - Admin permission set or equivalent, to create and activate the configuration.
• For non-Microsoft clients (Claude, ChatGPT, custom agents): a Microsoft Entra ID app registration, since only Microsoft clients use the preregistered application.
• A sandbox environment for the first activation. Data Query Tools queries run against your live database, so develop there first.
• Basic familiarity with how Business Central permission sets work, because they become the access boundary.

Step 1: Open the MCP Server Configurations page

Search for and open the Model Context Protocol (MCP) Server Configurations page in the Business Central web client. This is the single control surface for the MCP server: each configuration defines a name, description, active state, and a set of server features. The built-in default configuration ships with dynamic tool mode and read-only object discovery on, and it is used whenever a connection does not specify a configuration name.

Step 2: Create a dedicated configuration

Select New and give the configuration a clear Name and Description, for example FinanceQueries for a finance-team agent. Leave the Active switch off while you configure it. This is a small detail that catches people once: an active configuration is read-only, and its settings cannot be edited until you deactivate it. Create and configure the object first, review it, then activate.

Step 3: Activate Data Query Tools

In the Server Features section you will find three features:

• API Tools exposes the list of API pages and API queries your agents can access, curated by an admin.
• Dynamic Tool Mode lets agents discover tools dynamically instead of requiring manual configuration. It depends on API Tools, and disabling API Tools turns it off automatically. Use it when tool counts matter, such as the 70-tool limit in Copilot Studio.
• Data Query Tools (Preview) enables agents to run queries directly against your database. Select Activate to turn it on. No additional configuration is needed: there is no allow-list of tables to curate and no per-object read flag.

The last sentence is the whole setup, and it is deliberately different from API Tools. With API pages you set Allow Read, Allow Create, Allow Modify, and Allow Delete per object. With Data Query Tools there is no per-object gate; activating it means the agent can query any table the signed-in user is permitted to see.

Step 4: Keep edit tools blocked for a read-only agent

If this agent only answers questions, leave Unblock Edit Tools off. That switch controls whether API tools can perform create, update, or delete operations. Data Query Tools is read-only regardless, so a blocked-edit configuration plus Data Query Tools gives you an agent that can ask anything and change nothing.

Step 5: Activate the configuration

Turn the Active switch on. From this point the configuration and its tools are available to agents. If you need to change anything later, deactivate it first, edit, and reactivate.

Step 6: Connect your MCP client

Every MCP host connects to the same endpoint:

https://mcp.businesscentral.dynamics.com

Four HTTP headers select the context: TenantId, EnvironmentName, Company, and the optional ConfigurationName. How many you can omit depends on the host. Visual Studio Code with GitHub Copilot can omit all of them, so it is the fastest way to verify your setup. Copilot Studio requires the tenant, environment, and company headers, and you can pass your configuration name to pin the agent to the configuration you created instead of the default. Test the headers with your host rather than assuming.

One encoding rule is worth applying before it bites you. If your Company or ConfigurationName values contain non-ASCII characters, encode them Base64 UTF-8 in the format =?base64?<encodedvalue>?=. Copilot Studio handles the encoding for you; other hosts do not.

If you connect with Claude, ChatGPT, or a custom agent, register your own application in Microsoft Entra ID first. Microsoft hosts use a preregistered application, but third-party clients must bring their own registration.

Step 7: Run your first agent-composed query

Ask the agent something that has no API page behind it, for example: “Which items have had no sales in the last quarter?” The agent works through four documented tools:

1. bc_data_find_tables finds tables by keyword or semantic search.
2. bc_data_get_table_schema returns a table’s fields, which vary by environment and installed extensions.
3. bc_data_get_table_relations returns the relations the agent follows to join tables.
4. bc_data_query compiles and validates an AL query, and runs it only when returnData is true, with top, skip, and resultFormat parameters for paging.

That is the define, validate, run sequence: find tables, read schema and relations, write the query, confirm it compiles, then ask for rows. The queries are AL query objects, the same construct developers have used for years: data items name the tables, columns name the fields, and joins use DataItemLink. A simple query summing each customer’s balance from its detailed ledger entries looks like this (an illustration of the query shape, not captured tool output):

query 50100 "Customer Balances"
{
    QueryType = Normal;
    elements
    {
        dataitem(Customer; Customer)
        {
            column(No_; "No.") { }
            column(Name; Name) { }
            dataitem(DetailedEntry; "Detailed Cust. Ledg. Entry")
            {
                DataItemLink = "Customer No." = Customer."No.";
                column(Amount; Amount)
                {
                    Method = Sum;
                }
            }
        }
    }
}

The important property is that this is a known, compiled, typed artifact, not free-text SQL against your tenant. Business Central compiles it, and a malformed query fails with an AL diagnostic the agent can act on, which is a far better failure mode than a syntactically valid query returning the wrong rows.

Step 8: Audit the permission boundary before production

Because Data Query Tools has no per-table configuration, the signed-in user’s permission sets are the entire access boundary. Pick the account the agent authenticates as and enumerate what it can actually see. Authentication runs OAuth 2.0 authorization code flow with PKCE against Microsoft Entra ID, and audit trails show the user for each action, so the agent is the user for compliance purposes. If your permission sets are loose because historically only developer-reviewed pages read the tables, tighten them before switching this on in production. Agentic OAuth scoping matters beyond Business Central too: Google Workspace MCP servers face their own deadline, so enable the Google Workspace MCP agentic OAuth setting and create an agentic client ID before untagged OAuth clients are rejected.

Troubleshooting

The configuration page will not let me edit a setting. You activated the configuration before finishing. Active configurations are read-only by design. Deactivate it, make your edits, and reactivate.

The agent answers questions about some tables but not others. It can only reach tables the signed-in user is permitted to see, so check that account’s permission sets rather than the MCP configuration. There is no table allow-list in the configuration to blame.

bc_data_query fails with a compile error such as AL0343, AL0344, or AL0345. These are the standard AL query diagnostics, and they apply to the agent exactly as they apply to a developer: queries must define a top-level data item (AL0343), nested data items need a DataItemLink property (AL0344), and every column or filter must reference a real field (AL0345). The agent should correct the query from the error text and retry.

The agent cannot create or modify records. That is by design. Data Query Tools is read-only. If the agent needs to post documents or change statuses, configure API Tools with Unblock Edit Tools on and the relevant Allow permissions ticked on each API object, then give the agent those tools instead.

Connecting with a company name containing non-ASCII characters fails. Encode the Company or ConfigurationName header as Base64 UTF-8 in the =?base64?<encodedvalue>?= format, or connect through Copilot Studio, which performs the encoding for you.

Copilot Studio drops some of the standard APIs. Copilot Studio currently caps an agent at 70 tools. Turn on Dynamic Tool Mode so the agent discovers tools at runtime instead of binding every tool at design time; note that Dynamic Tool Mode requires API Tools to be enabled.

FAQ

Do I still need API pages for a Business Central agent? Yes for anything that writes. Create, modify, delete, and bound OData actions still run through API Tools with the relevant Allow permissions on each object. Data Query Tools only covers read-only analysis, so the pattern is API pages for the operations an agent performs and data queries for the questions it answers.

Is Run data queries with MCP Server generally available or in preview? Microsoft lists it as generally available on the update 29.0 whats-new table, with roadmap ID 573312 marked launched and GA October 2026. The in-product server feature, however, is labeled Data Query Tools (Preview). Plan against the preview label, since preview features can change.

Which AI clients can connect to the Business Central MCP server? Any MCP-compliant client: Copilot Studio, Visual Studio Code with GitHub Copilot or GitHub Copilot CLI, Claude, ChatGPT, and custom agents. Microsoft clients use a preregistered Entra application; Claude, ChatGPT, and other non-Microsoft clients require you to register your own Entra application.

Whose permissions does the agent act with? The signed-in user’s. Authentication runs OAuth 2.0 authorization code flow with PKCE against Microsoft Entra ID, so every operation uses that user’s identity and permission sets, and audit trails record the user.

Does the Business Central MCP server work on-premises? No. Microsoft documents the MCP server as applying to Business Central online only.

Can the agent answer multi-year trend questions with Data Query Tools? Only within what your tables retain in one company. It answers questions about one company in one environment at one moment. Multi-year or cross-system analysis still belongs in a reporting layer such as Power BI or a data warehouse.

Conclusion

Data Query Tools changes the economics of a Business Central agent project: questions that once required an AL extension and a deployment cycle now become a conversation the agent resolves in seconds, validated by the same compiler that constrains developers. Roll it out the way you would any data-access change: a sandbox first, a dedicated configuration, blocked edit tools for read-only agents, and a hard look at the permission sets of the account the agent signs in as. For the agent-building side, How to Use n8n Workflows as MCP Tools in Claude Code shows how to wire MCP into a code assistant, and Windsurf MCP Setup covers connecting MCP servers to another popular client. If your Microsoft data story also runs through Dynamics 365 and Dataverse, our n8n Dataverse tutorial shows how to automate that side with n8n. And when you are ready to turn agent answers into full automations, The Complete n8n Guide covers building, securing, and scaling n8n from scratch.

Frequently asked questions