business-central-mcp

bc_switch_company

Idempotent

Switch the active Business Central company in your session so later reads, writes, and actions target that company's records; re-open pages because previous page IDs become invalid.

Instructions

Switch to a different company within the current Business Central session. All currently open pages will be invalidated and their pageContextIds will become unusable -- you must call bc_open_page to re-open any pages you need in the new company context.

Use bc_list_companies first to see the available company names and verify the target company exists. The companyName must be an exact, case-sensitive match (a wrong-case or unknown name returns COMPANY_NOT_FOUND and leaves the session on its current company). After switching, all subsequent bc_open_page, bc_read_data, bc_write_data, and bc_execute_action calls will operate against the new company's data.

Do NOT switch companies in the middle of a multi-step workflow (e.g., between creating a Sales Order and posting it). Complete all operations in the current company first, then switch.

Example: { "companyName": "CRONUS International Ltd." }

Input Schema

TableJSON Schema

Name	Required	Description	Default
`companyName`	Yes	Exact company name to switch to. Use bc_list_companies to see available company names.
`operationId`	No	Optional idempotency key (e.g. a UUID you generate). Retrying with the same operationId and the same arguments returns the first call's stored result instead of running the change again, so a retry after a dropped connection or timeout cannot double-post. Reusing it with different arguments is rejected (OPERATION_ID_REUSED). If the first call's outcome is unknown, the retry returns OPERATION_IN_DOUBT: check the record's state before acting again under a new operationId. Every result of this tool carries replaySafe: true means BC's response proved that re-running the same call (even under a new operationId, after an unknown outcome) cannot apply the change twice -- the write was echoed as an absolute value, or the form it acted on is closed so BC rejects a re-run; false means a re-run may double-apply or nothing proved otherwise, so read the record back before retrying. Replay is time-limited: a completed entry is kept for BC_OPERATION_TTL (default 24h), after which the same operationId runs the call again; check with bc_get_operation before a late retry. A replayed result carries download metadata (fileName, contentType, sizeBytes, savedPath) but not the file bytes.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`newCompany`	Yes
`replaySafe`	Yes
`previousCompany`	Yes
`invalidatedPageContextIds`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.0.0Oct 15, 2026

addedInput schema / properties / operationId

Added value: +{
+  "description": "Optional idempotency key (e.g. a UUID you generate). Retrying with the same operationId and the same arguments returns the first call's stored result instead of running the change again, so a retry after a dropped connection or timeout cannot double-post. Reusing it with different arguments is rejected (OPERATION_ID_REUSED). If the first call's outcome is unknown, the retry returns OPERATION_IN_DOUBT: check the record's state before acting again under a new operationId. Every result of this tool carries replaySafe: true means BC's response proved that re-running the same call (even under a new operationId, after an unknown outcome) cannot apply the change twice -- the write was echoed as an absolute value, or the form it acted on is closed so BC rejects a re-run; false means a re-run may double-apply or nothing proved otherwise, so read the record back before retrying. Replay is time-limited: a completed entry is kept for BC_OPERATION_TTL (default 24h), after which the same operationId runs the call again; check with bc_get_operation before a late retry. A replayed result carries download metadata (fileName, contentType, sizeBytes, savedPath) but not the file bytes.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "invalidatedPageContextIds": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "newCompany": {
+      "type": "string"
+    },
+    "previousCompany": {
+      "type": "string"
+    },
+    "replaySafe": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "previousCompany",
+    "newCompany",
+    "invalidatedPageContextIds",
+    "replaySafe"
+  ],
+  "type": "object"
+}

First observedv1.5.0Jul 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing the real side effect: all open pages are invalidated and their pageContextIds become unusable, requiring bc_open_page to re-open them. It also documents the failure mode (wrong-case or unknown name returns COMPANY_NOT_FOUND and leaves the session on the current company) and the downstream effect on subsequent bc_open_page/bc_read_data/bc_write_data/bc_execute_action calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and its consequence, then guidance, then a minimal example — no filler sentences. The only minor redundancy is repeating the bc_list_companies advice already present in the schema's companyName description, though here it is paired with the verification rationale.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a session-mutating switch tool, the description covers the side effects, sequencing constraint, error behavior, and follow-up actions; an output schema exists and the operationId/replay contract is fully specified in the schema, so no further return-value detail is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents both parameters (including operationId's idempotency semantics in detail), which sets a baseline of 3. The description adds meaningful semantics beyond the schema for companyName: the match is exact and case-sensitive, and a mismatch returns COMPANY_NOT_FOUND without changing session state, plus a concrete example value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: 'Switch to a different company within the current Business Central session.' It is immediately distinguishable from siblings like bc_list_companies (which enumerates companies) and bc_open_page/bc_read_data (which read data).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use (verify via bc_list_companies first), when-not-to-use (do NOT switch mid-workflow, e.g. between creating and posting a Sales Order; complete operations in the current company first), and it names the alternative tool for discovery. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server