Skip to main content
Glama
SShadowS

business-central-mcp

by SShadowS
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

bc_open_page

Read-only

Opens a Business Central page by its numeric ID and returns its full state as sections, plus a pageContextId for page-scoped tools.

Instructions

Opens a Business Central page by its numeric page ID and returns its complete state as a list of sections. Each section has a sectionId, kind (header / lines / factbox / subpage / requestPage), caption, and the appropriate content shape. Card-shape sections (most headers, factboxes, requestPages) carry fields[] (and headers also carry actions[]). List-shape sections (lines, list-bodied headers, repeater subpages) carry rows[] and totalRowCount. The header section adapts to its page: it is card-shape on Card pages and list-shape on List pages -- the kind stays "header" either way for path stability. This is the entry point for interactive, page-scoped work -- it returns a pageContextId that the page-scoped tools (bc_read_data, bc_write_data, bc_execute_action, bc_navigate, bc_respond_dialog, bc_close_page, bc_lookup) take as input, plus a stateVersion you can pass as expectedStateVersion to bc_write_data / bc_execute_action to guard against stale state. (bc_query, bc_run_report, bc_search_pages, bc_list_companies, and bc_switch_company do NOT need a pageContextId.) For bulk, read-only data over standard entities, prefer bc_query -- it needs no open page. Use bc_search_pages first if you do not know the page ID for an entity.

Card pages (single-record views like Customer Card=21) return one header (card-shape) plus any FactBox sections attached to the page. List pages (Customer List=22) return a header (list-shape, rows[] populated). Document pages (Sales Order=42) return a header (card-shape), a "lines" list-shape section with the document lines, and any FactBoxes.

Option/enum fields and boolean fields in card-shape sections carry two extra properties: "options" (the allowed choices as [{text, value}]) and "selectedOption" (the currently chosen entry). Always use the "value" string from "options" as the SaveValue payload when writing an enum field -- do NOT guess or invent values. Example: Item Card "Type" field returns options=[{text:"Inventory",value:"0"},{text:"Service",value:"1"},{text:"Non-Inventory",value:"2"}] and selectedOption={text:"Inventory",value:"0"}.

Typical workflow: bc_open_page -> bc_read_data (refresh / filter / paginate a section) -> bc_write_data (edit fields in any section) -> bc_execute_action (post / release / delete) -> bc_close_page. Always call bc_close_page when done. Do NOT call this if the page is already open -- reuse the existing pageContextId. On BC Online the first call opens a local Microsoft sign-in window (password and Authenticator stay in that window; never pass them as tool arguments). Retry after completing sign-in.

Optional bookmark parameter opens a Card page to a specific record. Bookmarks come from list rows in any prior section.

Examples:

  • { "pageId": 22 } opens Customer List. Sections: [{ "sectionId": "header", "kind": "header", "rows": [...], "actions": [...] }] (no fields[] on a list-shape header).

  • { "pageId": 21, "bookmark": "..." } opens Customer Card. Sections include the header card plus FactBoxes (e.g. { "sectionId": "factbox:Customer Statistics", "kind": "factbox", "fields": [...] }).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageIdYesNumeric BC page ID (e.g., 22 for Customer List, 21 for Customer Card). Use bc_search_pages to find IDs.
bookmarkNoOpen the page to a specific record. Bookmarks come from list row results in bc_open_page or bc_read_data.
tenantIdNoBC tenant ID. Defaults to the server-configured tenant. Only needed in multi-tenant deployments.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
captionYes
isModalYes
pageTypeYes
sectionsYes
stateVersionYes
pageContextIdYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.0.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "caption": {
+      "type": "string"
+    },
+    "isModal": {
+      "type": "boolean"
+    },
+    "pageContextId": {
+      "type": "string"
+    },
+    "pageType": {
+      "type": "string"
+    },
+    "sections": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {},
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "stateVersion": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "pageContextId",
+    "pageType",
+    "caption",
+    "isModal",
+    "sections",
+    "stateVersion"
+  ],
+  "type": "object"
+}
  2. Changed2 schema fields changedv1.7.0
    • removedInput schema / properties / pageId / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
    • addedInput schema / properties / pageId / type
      Added value: +[
+  "string",
+  "number"
+]
  3. First observedv1.5.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only give readOnlyHint=true and openWorldHint=false, so the description carries real weight: it discloses the BC Online sign-in window behaviour and the instruction never to pass credentials as arguments, the pageContextId/stateVersion lifecycle, the stale-state guard via expectedStateVersion, and the obligation to call bc_close_page. That is substantive operational context beyond the annotations.

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 purpose and return shape, then workflow, then guardrails, with worked examples at the end. It is long, but nearly every paragraph maps to a distinct decision the agent must make; the enum/options narrative is the one stretch that could be tightened or deferred to bc_write_data.

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 stateful, page-scoped entry point, the description covers the return structure, the shape variation across Card/List/Document pages, the lifecycle (open -> read/write/act -> close), and the auth edge case. An output schema exists, and the description still sufficiently frames how sections should be interpreted, so an agent can call and consume this correctly.

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 baseline is 3, but the description adds real semantics: bookmark 'opens a Card page to a specific record' and 'Bookmarks come from list rows in any prior section', which tells the agent where the value originates. It also documents the options/selectedOption value-string convention for enum fields, which is directly relevant to payloads derived from this tool's output.

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 and resource ('Opens a Business Central page by its numeric page ID') and immediately defines the return shape (list of sections with sectionId/kind/caption/content). It explicitly differentiates itself from siblings, calling out that bc_query needs no open page and that bc_search_pages should be used first when the ID is unknown.

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 ('entry point for interactive, page-scoped work'), when-not ('Do NOT call this if the page is already open -- reuse the existing pageContextId'), and named alternatives for adjacent jobs (bc_query for bulk read-only, bc_search_pages for ID lookup). It also states which sibling tools do and do not need a pageContextId, removing all routing ambiguity.

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

Deploy Server

Other Tools