{"title":"Configure the Business Central MCP server","url":"https://jonas-paprotka.de/docs/dev-itpro/ai/configure-mcp-server/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/configure-mcp-server, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/ai/configure-mcp-server","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to configure the Business Central MCP server to enable AI agents to access and interact with your Business Central data and processes.","date":"2026-10-02","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Configure the Business Central MCP server","slug":"configure-the-business-central-mcp-server","at":0,"chars":20104},{"level":2,"title":"Configuration overview","slug":"configuration-overview","at":1314,"chars":1057},{"level":2,"title":"Prerequisites","slug":"prerequisites","at":2371,"chars":94},{"level":2,"title":"Create MCP server configurations","slug":"create-mcp-server-configurations","at":2465,"chars":4246},{"level":3,"title":"Manage the default configuration","slug":"manage-the-default-configuration","at":5950,"chars":761},{"level":2,"title":"Configure available APIs","slug":"configure-available-apis","at":6711,"chars":1682},{"level":2,"title":"Configure dynamic tool mode","slug":"configure-dynamic-tool-mode","at":8393,"chars":1351},{"level":2,"title":"Configure data query tools (preview)","slug":"configure-data-query-tools-preview","at":9744,"chars":1196},{"level":2,"title":"Validate a configuration","slug":"validate-a-configuration","at":10940,"chars":1654},{"level":3,"title":"Example 1","slug":"example-1","at":11572,"chars":473},{"level":3,"title":"Example 2","slug":"example-2","at":12045,"chars":549},{"level":2,"title":"Export and import MCP server configurations","slug":"export-and-import-mcp-server-configurations","at":12594,"chars":1417},{"level":3,"title":"Export a configuration","slug":"export-a-configuration","at":12981,"chars":532},{"level":3,"title":"Import a configuration","slug":"import-a-configuration","at":13513,"chars":498},{"level":2,"title":"Get the MCP server configuration connection string","slug":"get-the-mcp-server-configuration-connection-string","at":14011,"chars":1849},{"level":2,"title":"Choose how the tenant, environment, and company are specified","slug":"choose-how-the-tenant-environment-and-company-are-specified","at":15860,"chars":1211},{"level":2,"title":"How API object entries map to MCP server tools","slug":"how-api-object-entries-map-to-mcp-server-tools","at":17071,"chars":2589},{"level":3,"title":"Dynamic tool mode off<#tab/off>","slug":"dynamic-tool-mode-offtaboff","at":17604,"chars":1492},{"level":3,"title":"Dynamic tool mode on<#tab/on>","slug":"dynamic-tool-mode-ontabon","at":19096,"chars":564},{"level":2,"title":"Next steps","slug":"next-steps","at":19660,"chars":199},{"level":2,"title":"Related information","slug":"related-information","at":19859,"chars":245}],"text":"# Configure the Business Central MCP server\n> APPLIES TO: Business Central online\nThe Business Central MCP Server enables AI clients to connect to your environments, so agents within those clients can perform a range of interactions and tasks. Customers and employees can conversationally engage with Business Central data and logic from various channels, like Microsoft Copilot, Teams, Visual Studio Code, and websites.\nWhen you configure the MCP server, agents can perform tasks such as:\n View records: List customers, items, or other entities exposed through API pages and API queries.\n Edit records: Update customer information, item details, or other entity properties exposed through API pages.\n Create records: Add new customers, items, or other entities through API pages.\n Delete records: Remove entities through API pages when permissions allow.\n Perform actions: Execute OData actions attached to API pages or exposed by API codeunits, like posting documents or changing statuses.\nThe specific tasks available depend on your MCP Server configuration and the permissions you define for each API object.\nThis article explains how to enable and configure the Business Central MCP server in your Business Central environment so AI clients can connect to the environment's APIs and use them in their agents.\n## Configuration overview\nThe built-in default configuration has dynamic tool mode and read-only object discovery turned on. This configuration lets agents discover and read eligible Business Central API pages and API queries that the signed-in user has permission to use. This behavior means that without any extra setup in Business Central, agent makers can immediately create agents that read the data exposed by these APIs. Administrators can designate another active configuration as the default.\nIf you want to enable agents to create, modify, or delete entities and data, or invoke API actions, you must configure these operations on the MCP server. Configuring the Business Central MCP server involves adding API objects in individual configurations and defining the allowed operations. The operations are available as tools in Copilot Studio. See #how-api-object-entries-map-to-mcp-server-tools.\nWhen you enable and configure the MCP server, agent makers can use the individual configurations in Copilot Studio. See create-agent-in-copilot-studio.\n## Prerequisites\n You have at least the MCP - Admin permission set or equivalent permissions.\n## Create MCP server configurations\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Select New.\n1. Set these general fields:\n Field|Description\n -|-\n Name|Specifies the configuration's name. This name appears in Copilot Studio to assign the configuration to MCP server connection for an agent.\n Description|Specifies a brief description of the configuration.\n Active|Specifies whether the configuration and its tools are available for agents to use. Leave this switch off while you configure the server. An active configuration is read-only, so its settings aren't editable until you deactivate it.\n Unblock Edit Tools|Specifies whether APIs included as tools in the configuration can perform create, update, delete, or action operations. When this switch is turned on, the `Allow Create`, `Allow Modify`, `Allow Delete`, and `Allow Actions` permissions control these operations.\n1. In the Server Features section, enable the features your configuration needs.\n The following table describes each feature:\n Feature|Description|Setup\n -|-|-\n API Tools|Exposes the list of API pages and API queries your agents can access. Admins curate which API objects are available to agents.<br><br>Dynamic Tool Mode requires this feature to be enabled first.|Select Activate to turn on the feature. Then configure which API objects agents can reach. See #configure-available-apis.\n Dynamic Tool Mode|Agents discover tools dynamically instead of requiring manual tool configuration. Useful when you have many API objects and need to work around client tool limits (like Copilot Studio's 70-tool limit).|Select Activate to turn on. Select Configure to set whether agents can discover read-only objects beyond those explicitly added. See #configure-dynamic-tool-mode.\n Data Query Tools (Preview)|Enables agents to run queries directly against your Business Central database. This feature is currently in preview.|Select Activate to turn on. No additional configuration needed.\n> NOTE\n> Disabling API Tools automatically turns off Dynamic Tool Mode because Dynamic Tool Mode depends on API Tools. When you disable API Tools, any Discover Read-Only Objects setting is also cleared.\n1. In the Available APIs section, add API objects as tools to the configuration.\n To add an API object, set the Object Type, Object ID, and API Version fields, and then select the permissions as described in the following table. To automatically add standard Business Central API pages and API queries as tools, select Add All Standard APIs.\n> NOTE\n> API pages of subtype ListPart and CardPart aren't currently supported as MCP tools. Only top-level API pages can be added to MCP server configurations.\nPermission|Description\n-|-\nAllow Read|Specifies whether read operations are allowed for this tool.\nAllow Create|Specifies whether create operations are allowed for this tool.\nAllow Modify|Specifies whether modify operations are allowed for this tool.\nAllow Delete|Specifies whether delete operations are allowed for this tool.\nAllow Actions|Specifies whether actions are allowed for this tool. For API pages, this permission controls bound actions. For API codeunits, it controls whether the codeunit action can be invoked.\n1. After you finish configuring the server features and API tools, turn on Active. After activation, the configuration is read-only. To change its settings later, first turn off Active.\n### Manage the default configuration\nThe built-in default configuration has a blank name and is used when the MCP connection doesn't specify ConfigurationName. You can designate a named active configuration as the default instead.\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Select the active configuration that you want to use by default.\n1. Select Set as Default.\nTo go back to the built-in default configuration, select the designated default configuration, and then select Clear Default. A configuration that's currently designated as the default can't be deactivated until you clear the default setting or choose another default configuration.\n## Configure available APIs\nAfter you enable API Tools, you can curate which API pages and API queries agents can access.\n1. On the Server Features list, select the API Tools row.\n1. Select Configure.\n1. In the Available APIs section, select Select APIs.\n1. In the Select APIs dialog, search for or browse API objects.\n1. Select the objects you want to add, and then select OK.\n1. For each API object, set the allowed operations by selecting the checkboxes:\n Permission|Description\n -|-\n Allow Read|Specifies whether read operations are allowed.\n Allow Create|Specifies whether create operations are allowed.\n Allow Modify|Specifies whether modify operations are allowed.\n Allow Delete|Specifies whether delete operations are allowed.\n Allow Actions|Specifies whether actions are allowed. For API pages, this permission controls bound actions. For API codeunits, it controls whether the codeunit action can be invoked.\nBusiness Central enables only the permissions that apply to the selected API object type. API queries support read operations only. API pages can support read, create, modify, delete, and action operations, depending on the API object's capabilities.\nAlternatively, select Add All Standard APIs to automatically add standard Business Central API v2.0 pages and queries, or select Add APIs by API Group to add published API objects from a specific API group.\nWhen multiple published API versions are available for the same object, use the API Version field to choose the version that the MCP tool uses.\n> NOTE\n> API pages of subtype ListPart and CardPart aren't currently supported as MCP tools. Only top-level API pages can be added to MCP server configurations.\n## Configure dynamic tool mode\nBy using dynamic tool mode, agents can discover tools dynamically without requiring you to manually add each tool to your configuration. This feature is especially useful when you have many API objects and need to overcome client limits on the number of tools per agent.\nPrerequisite: API Tools must be enabled before you can enable dynamic tool mode.\n> NOTE\n> When API Tools are enabled and an MCP connection doesn't include the Company header, Business Central uses dynamic tool mode for API tools even if Dynamic Tool Mode isn't activated in the configuration. The MCP host can use list_companies to discover available companies, and operational tool calls must include the company parameter.\n1. On the Server Features list, select the Dynamic Tool Mode row.\n1. Select Configure.\n1. Set Discover Read-Only Objects to control agent access:\n  Off (default): Agents can only access the API objects you explicitly added in the Available APIs section.\n  On: Agents have read-only access to eligible API pages and API queries in your environment, even if you didn't add them as tools. The user must have permission to execute the API object and read its source table data.\n1. Select OK.\n> NOTE\n> If you disable API Tools, dynamic tool mode is automatically turned off and the Discover Read-Only Objects setting is cleared.\n## Configure data query tools (preview)\nBy using data query tools, agents can run queries directly against your Business Central database. This feature is currently in preview and subject to change.\n1. On the Server Features list, find the Data Query Tools (Preview) row.\n1. Select Activate.\nWhen you enable this feature, agents who use your MCP server configuration have access to data query tools they can use in their workflows. Data query tools are read-only and don't allow agents to create, modify, or delete data.\nThe following data query tools are available:\nTool|Purpose\n-|-\nbc_data_find_tables|Finds Business Central tables by keyword or semantic search. Use the searchText, searchMode, and optional top parameters.\nbc_data_get_table_schema|Returns fields for a table. Use this tool before writing a query because fields can vary by environment and installed extensions.\nbc_data_get_table_relations|Returns outgoing or incoming table relations. Use this tool to discover join paths for multi-table queries.\nbc_data_query|Compiles and validates an AL query. Set returnData to true to run the validated query and return rows. Use top, skip, and resultFormat for paging and large results.\n## Validate a configuration\nUse Validate before activating or sharing a configuration. Validation checks for common issues, such as API objects that no longer exist, missing parent API pages, and API page entries where Allow Modify is enabled but Allow Read is disabled.\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Open the configuration.\n1. Select Validate.\n1. If warnings appear, review Warning Message and Recommended Action.\n1. To apply a suggested fix, select the warning, and then select Apply Recommended Action.\n### Example 1\nThis simplified configuration allows agents to:\n Read, modify, create, and delete items\n Read and modify customers\nServer Features\nFeature|Status\n-|-\nAPI Tools|Activated\nDynamic Tool Mode|Not activated\nData Query Tools (Preview)|Not activated\nGeneral Settings\nUnblock Edit Tools: ON\nAvailable APIs\n|Object ID|Name|Type|Allow Read|Allow Create|Allow Modify|Allow Delete|\n|-|-|-|-|-|-|-|\n|30008|APIV2 - Items|Page|✓|✓|✓|✓|\n|30009|APIV2 - Customers|Page|✓|✓|✓||\n### Example 2\nThis simplified configuration allows agents to:\n Read, modify, create, and delete items\n Read and modify customers\n Read other eligible API pages and API queries\nServer Features\nFeature|Status\n-|-\nAPI Tools|Activated\nDynamic Tool Mode|Activated (Discover Read-Only Objects: On)\nData Query Tools (Preview)|Not activated\nGeneral Settings\nUnblock Edit Tools: ON\nAvailable APIs\n|Object ID|Name|Type|Allow Read|Allow Create|Allow Modify|Allow Delete|\n|-|-|-|-|-|-|-|\n|30008|APIV2 - Items|Page|✓|✓|✓|✓|\n|30009|APIV2 - Customers|Page|✓|✓|✓||\n## Export and import MCP server configurations\nYou can export MCP server configurations as JSON files, which makes it easier to share configurations with other users and across different environments. You can export existing configurations, modify them, and import them as new configurations. Alternatively, you can create new configurations from scratch in JSON format and import them.\n### Export a configuration\nTo export an existing MCP server configuration:\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Select the configuration you want to export from the list.\n1. On the Model Context Protocol (MCP) Server Configuration page, select Advanced > Export.\nThe configuration downloads as a JSON file to your device. You can edit this file in any text editor to modify settings or share it with other users.\n### Import a configuration\nTo import an MCP server configuration from a JSON file:\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Select Advanced > Import.\n1. Browse to and select the JSON configuration file you want to import.\nThe configuration imports as a new entry and appears in the list of available configurations. You can activate it and make any additional adjustments as needed.\n## Get the MCP server configuration connection string\nEach MCP server configuration has a connection string, which is a JSON definition that includes information for AI clients to connect to your Business Central environment. You can use the connection string to set up the MCP configuration in various clients, such as Visual Studio Code, to enable natural-language access to your Business Central data and processes.\nTo get your MCP server configuration connection string:\n1. Search for and open the Model Context Protocol (MCP) Server Configurations<https://businesscentral.dynamics.com/?page=8350> page in Business Central.\n1. Open the configuration from the list.\n1. On the Model Context Protocol (MCP) Server Configuration page, select Advanced > Connection String.\n The Connection String dialog displays the connection string similar to:\n ```json\n \"businesscentral\": {\n    \"url\": \"https://mcp.businesscentral.dynamics.com\",\n    \"type\": \"http\",\n    \"headers\": {\n    \"TenantId\": \"aaaabbbb-0000-cccc-1111-dddd2222eeee\",\n    \"EnvironmentName\": \"Production\",\n    \"Company\": \"CRONUS USA, Inc.\",\n    \"ConfigurationName\": \"MyMCPConfig\"\n    }\n }\n ```\n  url: The MCP server endpoint. This value is the same for all Business Central MCP configurations.\n  type: The connection protocol type. This value is the same for all Business Central MCP configurations.\n  TenantId: The Microsoft Entra tenant ID used by the Business Central environment. Required unless the MCP host supports omitting it.\n  EnvironmentName: The Business Central environment name. Required unless the MCP host supports omitting it.\n  Company: The company name in Business Central. Required unless the MCP host supports omitting it.\n  ConfigurationName: The optional name of your MCP configuration\n1. Copy the text or select Download to save it in a text (.txt) file on your device.\n## Choose how the tenant, environment, and company are specified\nWhether you can omit TenantId, EnvironmentName, or Company depends on the MCP host. Visual Studio Code with GitHub Copilot supports omitting all three headers. GitHub Copilot CLI supports omitting TenantId and Company. Copilot Studio doesn't require TenantId, but it requires EnvironmentName and Company. For other MCP hosts, check the host's support for determining the tenant from the signed-in identity and selecting environment and company values at runtime. ConfigurationName is optional for all hosts.\nWhen you omit TenantId, the server determines the tenant from the signed-in identity. Including EnvironmentName or Company pins that value for the connection. When a supported host omits Company, the server uses dynamic tool mode for API tools, requires a company parameter with each operational tool call, and exposes list_companies. When a host supports omitting EnvironmentName, the server requires an environmentName parameter on tool calls and can expose list_environments.\nFor details about detecting required parameters in non-Microsoft clients, see use-mcp-server-non-microsoft#check-available-configurations-and-tool-parameters.\n## How API object entries map to MCP server tools\nWhen you add an API object entry to an MCP server configuration, each allowed operation (read, create, modify, delete, or action) results in a corresponding tool in the MCP server. You can add these tools to agents in clients like Copilot Studio.\nDepending on the Dynamic Tool Mode setting, agent makers explicitly add these tools during design or the agent dynamically adds these tools at runtime. The following sections explain how tools are named and made available in each mode.\n### Dynamic tool mode off<#tab/off>\nWhen you turn off Dynamic Tool Mode, agent creators specifically apply individual tools to the agent during design. In Copilot Studio, the tool names follow this format:\nBusiness Central object permissions|Tool\n-|-\nAllow read|`List_<EntitySetName>_PAG<ID>` or `List_<EntitySetName>_QRY<ID>`\nAllow create|`Create_<EntityName>_PAG<ID>`\nAllow modify|`Modify_<EntityName>_PAG<ID>`\nAllow delete|`Delete_<EntityName>_PAG<ID>`\nAllow actions|`<ActionName>_<EntitySetName>_PAG<ID>` or `<ServiceName>_<ProcedureName>_COD<ID>`\nThe MCP server builds tool names from API metadata, not from the object caption. Names use PascalCase with underscores between parts. Page tools use the `_PAG<ID>` suffix. Query list tools use the `_QRY<ID>` suffix. Codeunit API action tools can use the `_COD<ID>` suffix when codeunit APIs are available. Some page and query tools can also include an API entity group prefix.\nFor example, if you specify the following settings on the MCP Server Configuration page:\nObject type|Object ID|Object Name|Allow read|Allow create|Allow modify|Allow delete\n-|-|-|-|-|-|-\nPage|30009|APIV2 - Customer|✓|✓|✓|✓\nThe following tools are available in the server:\n List_Customers_PAG30009\n Create_Customer_PAG30009\n Modify_Customer_PAG30009\n Delete_Customer_PAG30009\nThese tools appear in the MCP server and you can add them to agents in Copilot Studio. By using these tools, agents can perform the permitted operations on the specified API page objects.\n### Dynamic tool mode on<#tab/on>\nWhen Dynamic Tool Mode is on, agent makers in Copilot Studio can't select tools, but the system dynamically applies tools at runtime as needed.\nIn this mode, the agent uses these standard tools to search for and execute the needed tools from the configuration: bc_actions_search, bc_actions_describe, bc_actions_invoke.\n> NOTE\n> These system tools use a different naming convention (lowercase with underscores) because the MCP server provides them, not generated from object metadata like the other tools listed in the other tab.\n## Next steps\n create-agent-in-copilot-studio\n Connect to MCP server with Visual Studio Code<use-mcp-server-in-vscode>\n Connect to MCP server with non-Microsoft clients<use-mcp-server-non-microsoft>\n## Related information\nTransparency note: Semantic Metadata Search in Business Central<transparency-note-semantic-metadata-search>\nBusiness Central API Reference<../api-reference/v2.0>\nDevelop APIs with pages and queries<../developer/devenv-api>"}