The BC Dev Toolset extension gives Business Central developers a single command surface for common setup, container, deployment, runtime packaging, backup, test, and visualization tasks without having to run scripts manually.
For more information please refer to the GitHub repository.
What it does
It offers operations in functional areas:
- Development environment initialization
- Backup and Restore BC data from servers and containers, to containers
- Manage local clones for multi-app workspaces
- Handle external dependencies, licenses, certificates, server configurations, etc.
- Create/Update launch.json configurations
- Analyze and visually verify object ID range allocation
- Manage artifacts (app)
- publish or unpublish apps
- create and deploy runtime packages
- Run/Verify standard and page scripting tests
- Exposes container data to agents for full read and mutation operations through MCP, using a companion extension
- Manages and updates BCQuality skills for major agentic frameworks
Getting started
To start using the extension in a workspace, focus on these three operations first:
1. Install prerequisites
Run BC Dev Toolset: Install prerequisites.
Use this to prepare the workstation for the toolset. This operation is intended to install the main external requirements used by the toolkit.
2. Initialize workspace
Run BC Dev Toolset: Initialize Workspace. The PowerShell operation asks for the workspace name when a workspace file needs to be created; the opened folder name is suggested by default. MCP clients can supply workspaceName directly or answer the initializeWorkspace.workspaceName prompt. Initialization adds the workspace root under the workspace name and coordinates every discovered AL app as a workspace folder. It also adds each nested app path to files.exclude so it is not duplicated beneath the workspace-root view.
New local settings include two Container configurations: Local with targetType: Dev and includeTestToolkit: "false" for manual testing and debugging, and Local Test with targetType: Test and includeTestToolkit: "true" for automated testing. Container names use the workspace name with spaces replaced by hyphens; the Test container adds the suffix -test. Re-running initialization adds newly discovered apps and each missing default without replacing existing folder names, file exclusions, or configuration values, including existing toolkit settings. Defaults already named in local or shared workspace configurations are retained there without adding local duplicates. Conflicting container names in either settings source are reported and left unchanged; review the local and workspace settings, resolve the conflict, and rerun initialization to add the missing default.
This initializes your current project. You will actually do this for every project you start.
3. Open local settings
The default settings may be enough to get started. To review or customize your local setup, run BC Dev Toolset: Open Local Settings (JSON).
This opens .bcdevtoolset/settings.json. Start with these settings, changing them only as needed:
configurations: Review the Local target for manual testing/debugging and Local Test target for automated tests, or add the Business Central environments you want to use.
dependenciesPaths: Add folders containing dependency .app packages or paths to .zip archives if your project needs external dependencies.
licenseFile: Set the path to your Business Central license file if your environment requires one.
See the Settings reference for all options, including backups, runtime packages, and testing.
This is it, now you can start working on your project. Explore the toolset:
Run BC Dev Toolset: Show Operations List.
This opens a two-step picker: choose a category first, then pick an operation from that category.
All operations are available directly as well.
Run BC Dev Toolset: Show Help at any time to open the full repository README in VS Code's rendered Markdown preview.
BCQuality across agents
Set bcDevToolset.bcQualityPath in User settings to an absolute path for a dedicated microsoft/BCQuality checkout, for example:
"bcDevToolset.bcQualityPath": "C:\\Knowledge\\BCQuality"
This machine-scoped setting is not synchronized between machines and cannot be overridden by workspace settings. It is separate from .bcdevtoolset/settings.json. Setting a path opts into background initialization and maintenance on every extension activation/reload and whenever the setting changes. Git must be available on PATH. An absent or empty directory is cloned; an existing directory must be the root of a BCQuality checkout with its origin pointing to Microsoft's repository. Clean checkouts on main are updated with git pull --ff-only origin main. Local changes and other branches or detached revisions are preserved without pulling. Offline or failed updates retain the existing usable checkout and report a warning. Multiple VS Code windows serialize maintenance through locks; a busy window can retry using the update command.
The extension maintains one source skill named bcdevtoolset-bcquality in personal skill directories: ~/.copilot/skills for Copilot, ~/.agents/skills for Codex, and ~/.claude/skills for Claude Code. This broadly described adapter directs the agent to the checkout's skills/entry.md, preserving the actual request and project context. BCQuality's own Entry selects applicable skills across its layers; the agent follows its preparation and dispatch instructions. New upstream skills require no additional redirects. The clone does not need to be open in VS Code or included in any development workspace. The extension does not change project instructions or agent permission settings.
Start a new agent session after initial setup if the source skill has not appeared. Ask the agent to use bcdevtoolset-bcquality when explicit selection is needed. Discovery makes the source available for consideration; it does not force it into every task or grant permission to read external directories. Restricted agents may need access to the configured directory, including BCQuality's own generated knowledge index. Local clones and personal skills must be on the same host as the agent; remote or cloud sessions do not inherit files from another machine.
Commands:
- BC Dev Toolset: Update BCQuality retries initialization/update and adapter registration, then opens the status report.
- BC Dev Toolset: Show BCQuality Status shows the configured path, maintenance state, resolved commit, last attempt/success, installed adapters, and warnings or errors. Maintenance results also appear in the BC Dev Toolset output channel.
Changing the path refreshes unchanged managed adapters. After successful source registration, maintenance removes unchanged toolset-owned legacy bcdevtoolset-al-code-review, bcdevtoolset-al-plan-guidance, and bcdevtoolset-al-knowledge redirects. Clearing the setting disables maintenance and removes unchanged managed adapters while retaining the clone. User-created or edited adapters are left untouched and reported in status; extra files are preserved. Extension Development Hosts skip maintenance of personal BCQuality content and adapters; automated tests use isolated homes and checkouts.
Curated skill source
The extension can maintain an additional trusted GitHub skill repository independently of BCQuality. Set both machine-specific User settings when the repository has been created:
{
"bcDevToolset.curatedSkillsRepositoryUrl": "https://github.com/YOUR-OWNER/YOUR-SKILLS.git",
"bcDevToolset.curatedSkillsPath": "C:\\Knowledge\\CuratedSkills"
}
Leave both settings empty until the repository exists. They default to empty, are not synchronized between machines, and cannot be overridden by workspace settings. Configuring just one reports incomplete configuration without starting maintenance. Git must be on PATH. Stored-token access requires Git 2.31 or later; the toolset verifies support for temporary authentication settings before sending a token. GitHub HTTPS and SSH repository URLs are supported; never embed credentials in the URL.
Private HTTPS repositories can use Configure Curated Skills Access Token, under Curated Skills in Show Operations List or the Command Palette. Enter a GitHub personal access token in the masked input. It is stored per repository in VS Code's encrypted SecretStorage, outside settings and skill files, and is not synchronized between machines. Use a token restricted to the intended repository with read access to its contents, and satisfy any organization approval/SSO requirements. Cancelling the prompt leaves the stored value unchanged. Running the command again replaces the token; Remove Curated Skills Access Token deletes the token for the currently configured repository. Changing the repository selects a different credential entry; the old entry is retained, so select its URL again if you want to remove it.
Run Check Curated Skills Access to test the configured URL using a read-only remote reference request. It requires only the repository URL and reports the selected authentication source without cloning, updating, registering skills or displaying the token. Use it after setup or token renewal. An inaccessible private repository may be unavailable, denied, or require renewed credentials; diagnostics do not guess which cause applies. Configure/replace the token or check the account's access and organization policy before retrying.
Stored tokens apply only to HTTPS. With no stored token, Git uses existing credentials; SSH URLs use your existing SSH keys/agent. Git terminal credential prompts are disabled during background work; configure SSH authentication in advance. SecretStorage failures stop HTTPS access, and a rejected stored token never falls back to another account. Tokens are supplied temporarily to Git network processes through process-local configuration, with redirects disabled, and are excluded from command arguments, persistent Git configuration, status reports, logs and adapters. Token-bearing clone/fetch steps are separated from checkout/merge steps. Credential setup is human-only and is not exposed through MCP. Extension Development Hosts skip personal credential operations.
Checkout filters such as Git LFS do not receive the stored token. Sources that require private LFS content or submodules need separate Git authentication and setup; the toolset does not initialize submodules.
Provide a readable, nonempty regular file at skills/entry.md in the source repository. The extension registers one source adapter named bcdevtoolset-curated-source in ~/.agents/skills (for example C:\Users\Damjan\.agents\skills), alongside existing skills. As with BCQuality, this broadly described adapter directs the agent to the source's Entry instructions with the user's actual request and context. Entry owns discovery and selection of applicable skills, including future additions. The agent follows the source's dispatch and execution instructions, including any lifecycle ordering or composition rules, and resolves supporting files against the original checkout. A failed or unmatched route does not authorize invented substitute execution.
Keep native skills at skills/<name>/SKILL.md and supporting routing documents beside skills/entry.md, following your source's own contract. The toolset validates the entry point rather than maintaining a separate per-skill registry or imposing a directory-name length limit. Symlinked entry points are rejected. The checkout need not be a workspace folder. Only configure a source you trust: its instructions guide the agent's work. Discovery does not grant filesystem permissions; a restricted agent may need access to the checkout. Start a new agent session after registration if the source adapter has not appeared; request bcdevtoolset-curated-source explicitly when needed.
Activation/reload and either setting changing trigger maintenance. Missing or empty checkout directories are cloned; existing directories must be checkout roots with the configured origin. Clean checkouts on main are fast-forward updated. Local edits, other branches and detached revisions are preserved. A failed update retains existing usable content after revalidation and reports a warning; initial clone or discovery failures stop registration. The status retains an unknown side-effect state after a failed pull even when cached skill registration succeeds. Inspect the checkout before retrying an uncertain operation. Concurrent VS Code windows serialize checkout and adapter changes using locks.
Run BC Dev Toolset: Update Curated Skills to retry maintenance and open its report, or BC Dev Toolset: Show Curated Skills Status to inspect the last result without starting maintenance. A failed refresh returns a failed command result even when cached adapters remain available, sets updateFailed, and records no success timestamp for that attempt. Intentional dirty or pinned checkout skips remain warnings. Both commands appear under Curated Skills in Show Operations List and directly in the Command Palette; neither is an MCP tool. Reports include checkout revision, installed adapters, warnings, failure stage and side-effect state when relevant. Backend credential payloads are excluded from diagnostics.
After successful source registration, maintenance removes unchanged toolset-owned legacy bcdevtoolset-curated-<name> redirects. User-created or edited skills and extra files are preserved. Clearing both settings removes unchanged extension-owned adapters while retaining the checkout. Updating the path refreshes the unchanged source adapter. Changing the URL requires a matching dedicated checkout path; existing repositories are never repurposed. Extension Development Hosts skip personal checkout and adapter maintenance. Local checkouts and personal skills must be on the same host as the agent.
MCP server
The extension contributes an MCP server named BC Dev Toolset Operations in VS Code. MCP-aware agents can use it to run BC Dev Toolset operations for the current AL workspace, such as creating containers, publishing apps, invoking tests, or showing active licenses. Agents can call bc_dev_toolset_show_help or read bcdevtoolset://help/readme to consult the full repository README when helping users explore, configure, or troubleshoot the toolset.
PowerShell-backed operations still run in the visible BC Dev Toolset: <PowerShell executable> terminal. This keeps long-running work, such as container creation and artifact downloads, visible while the agent waits for the operation result.
The AL test MCP operation compiles the visible transcript and JUnit data into a bounded report. Successful prerequisite output is collapsed into stage status. A failed build includes up to 20 recognized AL compiler errors and omits warnings and informational entries; when compiler errors cannot be recognized safely, it includes the complete captured build diagnostics. Failed container-preparation and test stages include their diagnostics. Test results include totals and up to 20 actionable failure details without requiring a second build or test invocation.
Some operations require confirmation before they start. If an operation asks a supported question while running, the visible terminal shows the question and the operation pauses. The agent may answer low-risk operational questions when it has enough context, but sensitive prompts and destructive user decisions still require you to choose. Operations started from the Command Palette keep the normal terminal behavior and can always be answered directly in the terminal.
MCP operations with declared inputs use a non-mutating preflight call first: omit execute: true to receive all relevant questions, including conditional questions, then call the same tool with execute: true and the named answers. Test targets resolve from the workspace baseline and configured platform, identically for humans and agents. MCP operation tools also accept a promptAnswers object keyed by prompt ID for conditional prompts. Calling the same operation with answers while it is waiting resumes the existing session and retains all supplied answers for later prompts; it does not restart the operation. Sensitive decisions remain in the visible terminal.
You do not need to know the MCP tool names for normal use. Ask the agent for the BC Dev Toolset action you want, and the MCP server exposes focused operation tools for the agent to choose from.
bc_dev_toolset_ensure_containers is enabled by default when the toolset is deployed. It checks the containers named by effective Container configurations, starts stopped containers, restarts unhealthy ones, and waits up to 120 seconds per container for readiness. An explicit false MCP tool setting disables its separate agent-facing tool; container-dependent operations still check readiness as part of their own execution.
Codex
Codex does not automatically discover MCP servers contributed through the VS Code extension API. Run BC Dev Toolset: Configure Codex MCP Integration to add or update the bc-dev-toolset MCP server entry in your Codex configuration. The operation also enables automatic configuration maintenance and adds managed global Codex instructions so Codex knows to use BC Dev Toolset MCP operations in your AL workspaces. After an extension upgrade, the extension updates the versioned MCP server path on its first activation; restart Codex afterward to load the new server. You do not need to add these instructions to each AL repository.
Automatic maintenance is disabled while running an Extension Development Host so development checkouts do not replace the deployed extension path. The configure command can still be run explicitly when testing Codex integration.
Run BC Dev Toolset: Disable Codex MCP Integration to opt out and remove the extension-managed MCP entry and global instructions.
The Codex MCP server uses the VS Code terminal bridge belonging to the current workspace for PowerShell-backed operations. Multiple VS Code windows are supported concurrently: each extension host publishes an isolated, authenticated instance, and a Codex MCP process binds once to the live instance that owns its startup working directory. Keep the BC Dev Toolset extension active in each workspace where Codex should run operations in that window's visible terminal. A request whose workspace or bridge identity does not match is rejected instead of being routed to another window.
Other prerequisites
The extension is a VS Code host for the BC-Dev-Toolset runtime. It installs all the required components with a single operation. For practical use, you should expect to need:
Installing BC Dev Toolset also installs the official Microsoft AL Language extension automatically. It is a required VS Code extension dependency and supplies the platform-specific, signed ALTool used by the build and AL test operations.
ALTool discovery checks bin and bin/<platform> in the registered AL extension, then searches only that installation for relocated executables. Candidates must launch within five seconds and advertise the AL CLI compile command. Discovery enforces path containment, skips directory links, limits enumeration to 50,000 entries, and rejects ambiguous fallback candidates. The output channel records the AL extension version and selected executable. This handles relocation; CLI changes can still require a toolset update.
The AL compatibility workflow runs daily, on relevant pull requests, and manually against current stable and prerelease Microsoft AL packages on Windows. It validates the extension and compiles a dependency-free fixture through BuildAllApps.ps1, verifying that an .app was produced. Run the same smoke check locally with node vscode-extension/scripts/check-al-compatibility.js <AL-extension-installation-directory> (requires PowerShell 7). This checks discovery and compilation, not container deployment or projects requiring external symbols. Latest and stable release packaging also run npm run validate before packaging.
- Windows with PowerShell available. The extension uses
pwsh by default.
- Have access to or be an administrator on your workstation. The "Prerequisites" category operations require elevated access.
- .NET SDK 9 or 10 and MSDyn365BC.AL.Runner for the standalone
AL Runner Test operation; the install-prerequisites operation can configure both.
- Access to any required Business Central environments, credentials, licenses, certificates, or dependency packages used by your team.
Operations
Curated Skills
| Operation |
Description |
Update Curated Skills |
Maintains the configured source checkout and personal Codex skills, then opens the status report. |
Show Curated Skills Status |
Opens the current source maintenance status without starting maintenance. |
Configure Curated Skills Access Token |
Stores or replaces the current HTTPS repository token through masked input and encrypted VS Code SecretStorage. |
Remove Curated Skills Access Token |
Removes the current repository's stored token while preserving its checkout and skills. |
Check Curated Skills Access |
Checks repository reachability and the selected authentication source without cloning or updating. |
Update BCQuality |
Retries maintenance of the configured BCQuality checkout and agent skills, then opens the status report. |
Show BCQuality Status |
Opens the current maintenance status, checkout revision, installed agent skills, and any warnings or errors. |
These commands are available under Curated Skills in Show Operations List and directly from the Command Palette. They are not exposed as MCP tools. See Curated skill source and BCQuality across agents for their User settings and setup guidance.
Workspace
| Operation |
Description |
Initialize Workspace |
Creates the baseline BC Dev Toolset workspace structure and default settings content for the current workspace, including Git-ignored backup folders for Container configurations with missing or blank sqlBackupPath values. |
Open Local Settings (JSON) |
Opens .bcdevtoolset/settings.json for the current workspace. |
Clear App and translation artifacts |
Removes generated app and translation artifacts from the workspace. |
Build all apps in the workspace |
Uses the platform-specific ALTool bundled and signed with the required Microsoft AL Language extension to compile each AL project in dependency order. The toolset does not discover or invoke the unsigned global al .NET tool. Every app builds against an isolated copy of its own package cache plus freshly built packages for its declared workspace dependencies, preserving project cache isolation. |
Update launch.json files in all apps in the workspace |
Refreshes launch configurations for all apps in the workspace. |
Container
| Operation |
Description |
Check and start configured containers |
Checks distinct Container configurations, starts created or stopped containers, restarts unhealthy running containers once, and waits for a running and healthy state when a Docker health check exists. It reports missing containers without creating them. Container-dependent operations run this check automatically for existing configured containers and continue to skip missing containers where they did before. AL test tool and page script tests run the check on their selected container after creating it if needed, before restore, deployment, or test execution. |
Create/Overwrite Docker container based on the workspace app.json application version |
Creates or recreates a development container using the common application version from every workspace app. Mismatched values stop the operation and are reported by app.json path. If more than one Container configuration has a non-empty container value, choose one configuration or process all qualified configurations; duplicate container values abort the operation. Manual creation exports an initial SQL backup set when includeTestToolkit is true, targetType is Test, and sqlBackupPath is non-empty. |
Extract assembly probing paths from Docker container |
Extracts Service and .NET DLLs from an existing configured container into the .netpackages folder of each workspace app whose app.json target is OnPrem. After extraction, it adds "./.netpackages" to al.assemblyProbingPaths if that exact path is absent, preserving other paths. It writes to the selected workspace file, or to root .vscode/settings.json when the workspace is opened as a folder. It prefers the Microsoft.NETCore.App.Ref targeting pack and falls back to the Microsoft.NETCore.App shared runtime. If multiple containers are configured, the operation asks which one to use. The create-container operation also runs this step after building a configuration whose autoExtractAssemblies value is true. Manual extraction ignores autoExtractAssemblies. |
Add Test Toolkit to existing container |
Lists the container values from Container configurations and adds the Business Central Test Toolkit to the selected existing container. An empty or invalid selection aborts the operation. |
Update license files in all containers |
Applies the configured license file to container environments. |
Update server configuration in all containers |
Applies configured server settings to container environments. |
Backup
| Operation |
Description |
bc_dev_toolset_inspect_restore_environment |
Inspects container identity, runtime and database/service state for backup/restore diagnostics only, as described in the diagnostics report. |
Create and export SQL backup set from Docker container |
Creates SQL backup files from a Docker container environment. If more than one Container configuration has a non-empty sqlBackupPath, choose one container or back up all qualified containers. |
Create and export SQL backup set from BC service SQL Server |
Creates SQL backup files from a Business Central service SQL Server environment. You will require credentials with the ability to create remote Powershell sessions to the SQL Server host. |
Restore SQL backup set to Docker container |
Restores a saved SQL backup set into a Docker container, either through the manual operation or during automatic container initialization. If more than one Container configuration has a non-empty sqlBackupPath, choose which container to restore. Afterward, it reports platform/database/Microsoft application versions and, when matching same-major packages make the detected split safe to upgrade, forcibly closes active BC sessions and upgrades System Application, Base Application, and Application in dependency order with non-destructive schema synchronization. |
Automatic administrator setup after restore
Manual restores, restores during container creation, and restores during test preparation repair administrator access in every restored tenant. Password authentication creates the configured user if missing and reapplies the configured password for existing users. Windows authentication uses the outbound network identity, including runas /netonly. The administrator is enabled, account expiry is cleared, and SUPER is granted for all companies when missing. Setup failures stop the operation without rolling back the database restore.
Troubleshooting administrator setup
If authentication does not match, correct the selected container configuration and target container authentication setup before retrying. For Windows authentication, ensure the target container can resolve the outbound account.
If an extension blocks CLI User table validation/events, for example because no company is selected:
- Disable the offending app in the source environment, or uninstall it if disabling is unavailable or ineffective.
- Create a new backup, then restore it to the target container.
- After administrator setup completes, enable or reinstall the app in the restored target environment.
Tests
| Operation |
Description |
Run AL test tool tests |
Builds all workspace apps in dependency order before preparing the test container, so a failed build stops the operation before backup restore or deployment. It then runs tests once per workspace extension. Business Central discovers codeunits whose SubType is Test by extension ID, so test suite registration in an OnInstall procedure is not required. |
Run page script tests |
Runs page script test recordings and writes the results to the configured output location. |
AL Runner Test |
A BC Dev Toolset feature based on Stefan Maron's BusinessCentral.AL.Runner tool. It runs without a Business Central container and passes every workspace folder that contains an app.json file to one al-runner invocation. The operation resolves the configured Container release matching the workspace application baseline and passes its exact major/minor through --bc-version. Compatibility runs do the same for each explicitly configured newer release in sequence. The operation reports the requested release; unlike container modes, AL Runner does not expose an independently verified installed application version. Refer to the upstream GitHub repository for its capabilities, limitations, and CLI documentation. |
Automated test operations resolve only Container configurations whose targetType is Test. Dev, Production, and unspecified roles are excluded. AL Runner also uses Test-role configurations to resolve platform versions, but does not require a test toolkit because it does not use a BC container.
Compatibility test operations run the same test mode against every explicitly configured Container platform newer than the workspace app.json application baseline. They build once, execute targets sequentially, validate each container's installed Application release before restore/deployment, and report outcomes per target. A major-only target such as 23.0 accepts the latest cumulative update in BC 23; a non-zero minor such as 27.1 must match exactly. The AL Runner compatibility operation passes each configured release's exact major/minor to --bc-version.
Automated testing resolves only Container configurations with targetType: "Test". Dev, Production, and unspecified roles are never used. AL Runner also uses Test-role configurations to resolve platform versions, but does not require a test toolkit because it does not use a BC container.
Windows Smart App Control or an organizational App Control policy can block an AL Runner release whose executable assemblies are not signed with a trusted certificate. The prerequisite and test operations report the corresponding Code Integrity failure but do not weaken or bypass application-control protection. Use a signed upstream release when available, or ask the device administrator to approve an appropriate policy. See Microsoft's Smart App Control signing guidance.
AL Runner availability, application-control, and invocation failures are reported as tool failures with a clear statement that tests were not executed. The bc_dev_toolset_al_runner_test MCP response tells agents to suggest bc_dev_toolset_invoke_tests as the container-based fallback, but not to run it automatically. Genuine AL compilation and test failures are kept separate and do not receive this fallback guidance. AL Runner itself determines whether it supports the requested release.
Publish
| Operation |
Description |
Publish dependencies to a selected configuration |
Publishes dependency apps to one selected Container, Cloud, or OnPrem configuration. |
Publish workspace apps (excluding test apps) to a selected configuration |
Publishes workspace apps to one selected Container, Cloud, or OnPrem configuration. |
Unpublish all workspace apps from a selected configuration |
Unpublishes workspace apps from one selected Container or OnPrem configuration. |
Workspace app and runtime publishing exclude test apps identified by Microsoft Test Toolkit dependencies, using the same rule as launch configuration generation. Test execution workflows explicitly include test apps when preparing their test targets.
Each operation offers eligible named configurations across Dev, Test, and Production. MCP callers supply the exact configurationName. Only the selected target is prepared or changed. Production apps always use normal publishing; Dev and Test targets offer the normal/Dev endpoint choice. Extension data removal retains its explicit user prompt.
OnPrem Dev publishing uses server, the developer-services port, serverInstance, and optional tenant without requiring administration tools. OnPrem publishing, app inspection and service discovery use configuration-level useManagementCredentials, defaulting to remote. Select bc, remote or currentWindows; the bc/remote sets use Windows Credential Manager when their corresponding credential flag is true, otherwise their username/password settings. The selected bc/remote set must be configured. Select currentWindows explicitly for integrated Windows authentication. Missing stored entries, incomplete configured credentials and rejected identities stop the operation without trying another source. UserPassword Dev publishing requires HTTPS and credentials from the selected management set. SQL backup/restore retains its existing credential rules. Normal local OnPrem publishing requires management cmdlets on the service host, loaded already or through an absolute loadOnPremMgtModule path. Remote publishing and explicit alternate local identities use the shared WinRM staging and additive install/upgrade path; remote unpublishing uses the same selected management identity and preserves extension data.
Runtime
| Operation |
Description |
Publish stored runtime packages (excluding test apps) to a selected configuration |
Publishes existing runtime packages to one selected Container or OnPrem configuration across Dev, Test, and Production. Cloud targets are excluded. |
Create deployment runtime packages for all apps in the workspace (not compile/build validation) |
Builds deployment runtime packages for all workspace apps. This is not a substitute for ordinary AL compile/build validation. |
Visualization
| Operation |
Description |
Prepare object id range data for visualization |
Collects declared ranges and actual numbered AL object IDs per workspace app and object type. Source scanning ignores comments and literals, includes all conditional compilation branches, and excludes dependency caches and nested apps. Repeated IDs within an app/type count once. |
Show object id range visualization data |
Opens the range pool chart, followed by an expandable app/type tree of contiguous occupied ID ranges (gaps excluded) and a counts matrix with app, object type, and grand totals. Prepare data again to add actual usage to older visualization files. |
Prerequisites
| Operation |
Description |
Show BcContainerHelper versions (installed and available) |
Shows the installed and available BcContainerHelper versions. |
Install/Update Prerequisites |
Installs and updates the main prerequisites used by the toolset, including BcContainerHelper, Node.js, @microsoft/bc-replay and its matching Playwright browsers, .NET SDK 9/10, and MSDyn365BC.AL.Runner. If required Windows container features cannot be enabled, later installation steps are skipped and the operation offers to open the guarded uninstall flow. |
Uninstall Prerequisites |
Detects Docker Engine, BC Replay, AL Runner, Node.js, Git, BcContainerHelper, and Windows container features, then asks separately before removing each component. Every prompt defaults to keeping the component installed. The shared .NET SDK is retained. |
Install/Update Microsoft PowerShell |
Updates the Windows PowerShell installation used for the toolkit setup flow. |
MCP Configuration
| Operation |
Description |
Show MCP status |
Shows the extension MCP API, server, protocol/instance identity, bound workspace, terminal bridge, and runtime status. Authentication tokens are never displayed. |
Configure Codex MCP integration |
Enables automatic maintenance, adds or updates the BC Dev Toolset MCP server entry in Codex configuration, and adds managed global Codex instructions. |
Disable Codex MCP integration |
Disables automatic maintenance and removes the extension-managed Codex MCP entry and global instructions. |
Settings
The Marketplace supports a pre-release channel for this extension. If you opt in to the pre-release version in VS Code, you can receive main-branch extension updates before the next stable release.
The extension uses three settings layers:
At startup, legacy dam-pav.bcdevtoolset and dam-pav.bcDevToolset setting names are automatically migrated to bcDevToolset in user, workspace, and folder settings. Contents are preserved and completion is reported without a confirmation dialog. Conflicting destinations or unsaved files are left unchanged and reported.
| Settings layer |
Location |
| VS Code extension |
bcDevToolset.* in VS Code settings |
| Workspace |
bcDevToolset in the .code-workspace file |
| Local |
.bcdevtoolset/settings.json |
VS Code extension settings
| Setting |
Description |
bcDevToolset.toolsetPath |
Overrides the central BC-Dev-Toolset runtime location. Default: %LOCALAPPDATA%\BC-Dev-Toolset\toolset on Windows. |
bcDevToolset.powershellExecutable |
PowerShell executable used to run operations. Default: pwsh. Operations reuse a dedicated BC Dev Toolset: <executable> terminal when it is already open. |
bcDevToolset.localSettingsPath |
Workspace-relative path to the local settings file passed to operations. Default: .bcdevtoolset/settings.json. |
bcDevToolset.codexMcpIntegration.enabled |
Machine-level opt-in for automatically keeping the global Codex MCP configuration synchronized with the installed extension version. The configure and disable commands manage this setting. Default: false. |
bcDevToolset.shortcuts |
Shortcut mode used for container creation flows. Default: None. |
bcDevToolset.hostHelperFolder |
BcContainerHelper host helper folder used by runtime operations. Default: C:\ProgramData\BcContainerHelper. |
bcDevToolset.curatedSkillsRepositoryUrl |
Machine-specific User URL of the trusted GitHub skill source; empty by default. Set together with curatedSkillsPath once the repository exists. |
bcDevToolset.curatedSkillsPath |
Machine-specific User path to a dedicated source checkout; empty by default. Registers managed personal Codex adapters under ~/.agents/skills. |
Workspace settings
These are stored in the workspace file. AL settings such as al.symbolsCountryRegion and al.assemblyProbingPaths are directly under settings; the remaining toolset settings are under bcDevToolset.
| Setting |
Description |
al.symbolsCountryRegion |
Business Central artifact region. Default: w1. |
al.assemblyProbingPaths |
Workspace initialization and assembly extraction add "./.netpackages" if that exact path is absent, preserving other entries. The path resolves from each app folder and points to the DLLs extracted for OnPrem apps. Remove older folder-level al.assemblyProbingPaths overrides from app .vscode/settings.json files to use the workspace setting. |
selectArtifact |
Artifact selection strategy. Default: Latest. Another common value is Closest. |
testBuildWarningsAsErrors |
Boolean, false by default. Set to true in shared workspace bcDevToolset settings or local .bcdevtoolset/settings.json to block Run AL test tool tests when its build emits compiler warnings. An explicit local value (including false) overrides the workspace setting. The operation stops before container preparation and test execution; the MCP report includes the warnings and instructs the agent to resolve them before rerunning. Standalone builds, page script tests, and AL Runner tests are unaffected. |
testIsolationDisabledCodeunits |
Optional integer codeunit IDs (for example [60990]) for AL integration tests requiring disabled isolation. Set this in shared settings.bcDevToolset or local .bcdevtoolset/settings.json; an explicit local array replaces the shared list, and [] clears it. Duplicates are removed; invalid IDs are rejected before build/container preparation. Selected tests run under 130451, all others under 130450, with extension-scoped discovery and one combined report. This is not restricted to any Business Central version; compatibility depends on the available runner, discovery and filter capabilities. Unmatched IDs fail the run. Committed data can persist: non-isolated tests must manage setup, cleanup and recovery after failure. Page-script and AL Runner tests are unaffected. |
configurations |
Shared target definitions for the workspace. These are useful when a team wants common environment entries available to everyone. |
Each workspace configuration entry can contain:
| Setting |
Description |
name |
Display name of the target. Entries named sample are placeholders and are ignored by operations. |
serverType |
Target type. Valid values: Container, Cloud, OnPrem. |
targetType |
Intended role of the target. Valid values: Dev, Test, Production. |
autoUpdateLaunchJson |
Optional override controlling whether this entry is included when launch.json files are updated, both manually and after container creation. It applies to all serverType values but does not change target-role routing: Dev entries go to apps without Microsoft Test Toolkit dependencies, and Test entries go to apps with those dependencies. When omitted, the effective value is true for entries matching the app's role. |
server |
Business Central server name for OnPrem. |
serverInstance |
Business Central server instance for OnPrem. |
container |
Docker container name for Container. Create-container processing only includes Container configurations with a non-empty container value, and duplicate container values abort the operation. |
multitenant |
Explicit container mode passed to New-BcContainer by the Create container operation. When omitted, creation infers the mode from a compatible backup set. If neither the setting nor the backup determines the mode, the parameter is omitted and BcContainerHelper decides. An explicit value has priority; creation aborts with an explanation if it conflicts with the detected *.app.bak or *.database.bak backup type. Valid only for Container. |
port |
Service port for OnPrem. |
environmentName |
Business Central environment name for Cloud. |
includeTestToolkit |
Whether a container target includes the test toolkit. |
tenant |
Tenant identifier for Cloud or OnPrem. |
authentication |
Authentication mode. Valid values: UserPassword, Windows, AAD. |
bcUser |
Business Central service user name. |
bcPassword |
Business Central service password. |
admin |
Obsolete fallback for bcUser. Use bcUser instead; this field will be removed in the next major release. |
password |
Obsolete fallback for bcPassword. Use bcPassword instead; this field will be removed in the next major release. |
network |
Optional Docker network passed to New-BcContainer for Container targets. Suggested Windows container network values include NAT, transparent, l2bridge, l2tunnel, overlay, and none; custom Docker network names are also allowed. For suggested network names, the toolset verifies that the Docker network exists with the expected driver and creates missing creatable networks, for example docker network create -d transparent transparent. Custom network setup is left to the user. Use a transparent network when the container should appear on the LAN with a real address. |
hostIP |
Optional host.containerhelper.internal IP address passed to New-BcContainer. |
updateHosts |
Optional switch controlling whether New-BcContainer updates the host machine's hosts file. Defaults to true when omitted. Valid for Container. |
autoExtractAssemblies |
Boolean controlling whether assembly extraction runs automatically after this container is built. Defaults to false when omitted. Valid only for a Container when at least one workspace app's app.json target is OnPrem; the manual extraction operation ignores it. |
autoRestoreBackup |
Boolean controlling whether container creation and Test operations automatically restore a compatible backup set from sqlBackupPath. Defaults to true when omitted; set it explicitly to false to disable automatic restore. Valid only for Container; manual restore ignores it. |
macAddress |
Optional container MAC address passed to New-BcContainer. Valid when serverType is Container and network is transparent. Use Docker's colon-delimited MAC address format, for example 02:42:ac:11:00:02. |
IP |
Optional static container IP address passed to New-BcContainer. Valid when serverType is Container and network is transparent. Leave empty to let the selected network assign the address, for example through DHCP. |
dns |
Optional DNS value passed to New-BcContainer. Valid when serverType is Container and network is transparent. HostDNS adds the host DNS servers; explicit DNS server values are also allowed. Use a comma-delimited string for multiple DNS servers, for example 8.8.8.8,1.1.1.1. |
memoryLimit |
Optional container memory limit passed directly to New-BcContainer. Valid only for Container. Use a positive whole-number size ending in M or G, for example 16G. When omitted or empty, BcContainerHelper chooses its default (currently 8G for Hyper-V isolation). |
sqlMemoryLimit |
Optional SQL Server memory limit passed directly to New-BcContainer. Valid only for Container. Use a positive whole-number size ending in M or G, or a percentage from 1% through 100%, for example 2G or 25%. When omitted or empty, BcContainerHelper chooses its default. |
databaseUser |
Optional SQL user for database operations. |
databasePassword |
Optional SQL password for database operations. |
sqlBackupPath |
Folder used for SQL backup files for this configuration. Valid only for Container. Relative paths are resolved from the workspace root and may resolve outside the workspace; absolute local drive paths are also supported. Container backup and manual restore use the path from the selected Container configuration, while automatic restore during creation uses it only when autoRestoreBackup is true. With includeTestToolkit set to true, Test-operation creation always exports an initial backup here; manual creation exports one only when targetType is also Test. BC service SQL Server backups export into the configured Container backup folders. |
remoteUser |
Optional PowerShell remoting user. |
remotePassword |
Optional PowerShell remoting password. |
serverConfiguration |
Additional Business Central server configuration entries as KeyName and KeyValue pairs. |
Container artifact type comes from workspace apps' app.json targets: if any app targets OnPrem, the container uses OnPrem artifacts; otherwise it uses Sandbox artifacts. Container launch entries use that same type. Cloud launch entries use Sandbox and are skipped for apps targeting OnPrem. An omitted app target defaults to Cloud. Existing configuration environmentType entries are ignored and can be removed.
Initialize Workspace fills missing or blank sqlBackupPath values in local and workspace Container configurations with .bcdevtoolset/.backups/<configuration name> and creates those folders. Existing non-empty paths are preserved. The .bcdevtoolset/ Git ignore rule covers these backups. Folder names are normalized by replacing invalid characters and trailing periods or spaces with underscores; reserved Windows device names receive an underscore prefix, and empty names use _. Configuration names in settings are preserved. Generated paths are unique across workspace and local Container configurations, using numeric suffixes such as _2 when normalized names collide (case-insensitively). Existing configured destinations are reserved before assigning new defaults; explicit shared paths remain unchanged. Different containers can use different folders; set the same folder on multiple Container configurations only when sharing is intentional.
Local settings
These are stored in .bcdevtoolset/settings.json and are intended for developer-specific values.
| Setting |
Description |
licenseFile |
Path to the Business Central license file. |
certificateFile |
Path to the certificate file used by local operations and runtime packaging. |
packageOutputPath |
Folder where generated packages are written. |
dependenciesPaths |
Folders containing dependency .app packages, or direct .zip file paths. |
dependenciesPath |
Deprecated legacy single folder containing dependency app packages. It is still read for compatibility, but users should migrate to dependenciesPaths. |
recordingsPath |
Folder containing page scripting recordings. |
pageScriptTestResultsPath |
Folder where page script test results are written. |
pageScriptTestHeaded |
Whether page script tests should run headed. |
configurations |
Developer-local target definitions. These use the same structure as workspace configurations and are merged with them at runtime. |
The extension adds JSON validation for .bcdevtoolset/settings.json, so VS Code can help you keep the local settings file in shape while editing it.
Run BC Dev Toolset: Configure MCP Tools to select tools for Local, Workspace, or User settings. Workspace and User selections are stored as booleans in "bcDevToolset": { "mcpTools": { ... } }. Saving writes the complete selection at that scope, including values equal to the inherited setting, so each scope retains its own decision. Local entries override workspace entries, which override user defaults per tool. Restart the MCP server/client after changes.
On a fresh installation, Get Workspace, Get Operation Status, Answer Operation Prompt, and Invoke AL Tests default to enabled. Every other tool defaults to disabled. Explicit values at Local, Workspace, or User scope override the next less granular level per tool.
Local selections are stored in the top-level mcpTools object in .bcdevtoolset/settings.json (or the workspace-relative bcDevToolset.localSettingsPath). Local values override workspace values, then user values, per tool. In manually edited settings, omitted switches inherit the next level. Restart the MCP server/client after editing local selections.
BC Data access
BC Data lets an MCP agent discover companies and tables, inspect schemas, read records and perform explicitly permitted record changes in your configured Business Central Container, Cloud and OnPrem environments (Dev, Test or Production). The extension bundles the BC Dev Toolset Data companion app. Installing the extension makes the app available; you must initialize access on each target and enable the tools you want to use.
Reserve object IDs 99100..99149 for the companion app. Your apps and other installed extensions must steer clear of this range if you want to use BC Data. An object ID conflict can block companion installation or upgrades and prevent data access. Before initializing or enabling automatic provisioning, check all installed apps and your own object ranges, and confirm that the target license permits these IDs. The range applies to the main companion app; its development test app is not installed with this feature.
Set up a target
- Configure a Container, Cloud or OnPrem target with role Dev, Test or Production and an exact, unique configuration name. BC23 is the minimum supported baseline.
- Configure authentication as described below.
bcCredential: true and remoteCredential: true select Windows Credential Manager for that credential set and ignore its plaintext fields. False or omission uses the corresponding username/password settings. OnPrem operations select their set through useManagementCredentials and useDataCredentials.
- Run BC Dev Toolset: Initialize BC Data Access, select one named Container, Cloud or OnPrem configuration (Dev, Test or Production), and confirm initialization. MCP callers supply the exact configuration name from the same choices. It validates the bundled Cloud-compatible app, installs or upgrades the companion and checks service readiness. Initialization does not grant user permissions or enable MCP data tools. If deployment succeeds but readiness fails, investigate the reported prerequisite before retrying. Compatible equal/newer companion versions are preserved; incompatible newer versions are rejected without downgrade.
- Grant the BC user BCD DATA EXECUTE (or equivalent service execution rights) and the native read permissions needed for Company, Table Metadata and the business tables being queried. FlowField reads also require access to their source tables. The companion does not elevate permissions; native security filters apply.
- Run BC Dev Toolset: Configure MCP Tools, enable the desired data tools and restart the MCP client. All data tools default to disabled. Use connection discovery and readiness to verify the selected target before reading business data.
Cloud configurations require tenant and environmentName. Initialization uses BcContainerHelper device login and normal per-tenant extension deployment through the automation API, including production environments. Run BC Dev Toolset: Sign in to BC Data for the selected Cloud configuration before data calls. Data calls reuse that VS Code Microsoft session silently for the configured tenant; tokens stay in the extension host. The signed-in account needs BC access, companion permissions, and native table permissions. Deployment additionally requires automation API extension-management permissions and an accessible company.
OnPrem configurations require server and serverInstance. During Initialize BC Data Access, a missing bcData.baseUrl is discovered using Get-NAVServerConfiguration through the same administrative connection used for SQL discovery and saved to the original configuration. Discovery prefers PublicODataBaseUrl, adding /ODataV4 when needed; otherwise it uses the configured server hostname, instance, ODataServicesPort and ODataServicesSSLEnabled. Both ODataServicesEnabled and ODataServicesV4EndpointEnabled must be enabled. An explicit bcData.baseUrl is preserved and bypasses discovery. Initialize before using BC Data tools; discovery does not run on each data request. The OData port is independent of the developer-services port. The endpoint must use the configured server hostname, including when an advertised public URL is present; set server to that hostname or supply a compatible explicit URL. bcData.tenant overrides the configuration tenant, otherwise the latter (or default) is used. OnPrem OData readiness, company/schema discovery, reads and mutations use configuration-level useDataCredentials, defaulting to bc. Its values are bc, remote and currentWindows. The selected bc/remote set uses its stored entry when bcCredential/remoteCredential is true, otherwise bcUser/bcPassword or remoteUser/remotePassword. The selected bc/remote set must be configured. Select currentWindows explicitly for integrated Windows authentication. Incomplete, missing stored or rejected configured credentials fail without switching identities. currentWindows requires Windows endpoint authentication. UserPassword uses HTTPS and the selected explicit credential set. Initialization uses useManagementCredentials (default remote) for service discovery, inspection and deployment, then useDataCredentials for OData readiness. Stored identities retain the existing project scope. No automatic selection is supported. Cloud OAuth, container access and SQL backup/restore retain their existing credential behavior.
Containers retain the default http://<container>:7048/BC/ODataV4 endpoint. Windows and UserPassword authentication are supported. Optional bcData.provisioningEnabled remains a container-lifecycle feature; remote targets are initialized explicitly. All data tools still default off, and mutations additionally require the connection's mutation allowlist or all-operations switch, including on Production targets.
Publishing access is a prerequisite of initialization, as with the publishing operations. Failures identify authentication, installed-app inspection, publishing or readiness and include relevant recovery guidance and an HTTP status when available. SaaS deployment failures point to Extension Deployment Status Details in Business Central. A publishing error can leave deployment pending or partially completed; inspect its status and the installed companion version before retrying. A readiness failure after publishing is reported separately. The operation does not automatically retry or switch deployment methods. If this machine cannot deploy apps to a target, an administrator can install the bundled companion through their normal deployment process. BC Data calls then need only the reachable OData endpoint and data permissions; they do not require publishing or management access.
The six read-only tools are bc_dev_toolset_data_list_connections, bc_dev_toolset_data_list_companies, bc_dev_toolset_data_get_readiness, bc_dev_toolset_data_find_tables, bc_dev_toolset_data_get_table_schema and bc_dev_toolset_data_read_records. Connection discovery is offline; other calls require the companion and its published BCDData service. Record calls require an explicit company. Connection IDs are the exact configuration names; duplicate names across shared and local settings are rejected.
For automatic companion maintenance, set "bcData": { "provisioningEnabled": true } on each desired Container configuration. Container creation/start and test preparation then maintain the companion. This defaults to false and is independent of tool selection. Turning it off preserves the installed app. Explicit initialization remains available without automatic maintenance. Data calls themselves do not install apps.
For containers, the default endpoint is http://<container>:7048/BC/ODataV4, tenant default. Optional container settings such as "bcData": { "baseUrl": "https://container:7048/BC/ODataV4", "tenant": "default" } override it. Stored-credential endpoints must use the configured container hostname. TLS uses normal certificate validation; live HTTPS qualification is pending. Credentials and endpoints cannot be supplied as tool arguments.
Enable record changes
Enable bc_dev_toolset_data_mutate_records in Configure MCP Tools and allow operations on each target. Set "bcData": { "allowedAllMutationOperations": true } to permit insert, modify, rename and delete. This boolean defaults to false; when true it takes priority over allowedMutationOperations, whose value is ignored. When false or omitted, use the list to allow a subset, for example "bcData": { "allowedMutationOperations": ["insert", "modify", "rename"] }; an omitted or empty list permits no writes, and adding "delete" permits deletion. The override requires a JSON boolean, not a string. Each call specifies exactly one operation on one record; the tool switch and native BC permissions are still required.
Writes require companion 0.1.10.0 mutation protocol 1, published BCDDataWrite, BCD DATA WRITE (or equivalent grants) and the user's native business/related-table permissions. Initialization does not assign these rights. BCD DATA EXECUTE only grants read-service execution. A readiness mutation capability describes server support, not permission to write.
Insert and modify accept ordered field assignments. Modify, rename and delete require the record's SystemId and exact string expectedVersion from a read; rename also requires the complete primary key in key order. Native validation and triggers run. Decimal and BigInteger values are strings. Null, system/content assignments and unqualified FlowField writes are rejected. Generic tools cannot read or change the companion's internal receipt table.
Each write call has a bounded receipt scope and may retry the identical request once after uncertain transport. An unknown outcome requires reconciliation with the target record: repeating the MCP tool call creates a new command and can apply a second change. A failed scope closure does not undo a successful write. Receipt guarantees cover the database transaction and uninterrupted history, not external trigger effects or database restore/copy.
Read limits and connection changes
Reads support ordinary physical application tables, native filters, selected FlowFields and primary-key ascending pagination. A page contains at most 100 rows and 50 selected fields. BLOB/Media values return descriptors; unsupported table or scalar types fail explicitly. Pages are not snapshots, and a record's row version does not cover changes to FlowField dependencies. Reduce the selected fields or page size if a response exceeds the companion's size limit.
Continuation tokens expire after 30 minutes and are bound to the target, company, query and extension-host session. Settings changes and extension-host reloads invalidate them. Reload the extension host after external app/container changes. Stored credentials are resolved afresh, so password rotation and removal are observed without a persistent credential cache.
See the BC Data design and compatibility evidence and qualification limits for details.
Remote OnPrem dependency publishing uses PowerShell remoting to managementServer (or the host from server), uses the identity selected by useManagementCredentials without switching identities after failure, and automatically loads the selected BC service's administration tools. It copies configured .app files and ZIP archives into a temporary server folder, publishes prerequisites first using the newest supplied version per app ID, skips already installed versions, and synchronizes or upgrades without uninstalling apps or deleting extension data. It uses the configured tenant (default default) and cleans up staging and sessions on success or failure. Local dependency publishing continues to use locally loaded administration tools or loadOnPremMgtModule.