business-central-mcp

bc_upload_file

Destructive

Upload a local file or base64 content into Business Central's open file-upload dialog, resuming the page's suspended AL upload code after the page action opens the picker.

Instructions

Upload a local file into a Business Central file-upload dialog, driving the page's AL Upload/UploadIntoStream code on the uploaded stream. This is a TWO-STEP flow: first invoke the page's upload action (bc_execute_action, e.g. "Import Layout" on Custom Report Layouts / page 9650) so BC opens the file-picker dialog (a FileUploadForm, returned in dialogsOpened), then call bc_upload_file with that page's pageContextId. The file is sent as a multipart POST to BC's DynamicFileUploadHandler over the same authenticated session, and the dialog is closed afterwards — exactly what the web client does — which resumes the suspended AL code on your bytes.

The upload targets the page's open FileUploadForm dialog automatically; optionally pass formId (the dialog formId from bc_execute_action's dialogsOpened) to target it explicitly. The call FAILS with a clear error instead of uploading when no FileUploadForm dialog is open — BC would otherwise silently discard the bytes (HTTP 200 with no effect), e.g. when the action failed and opened an error dialog instead, or when the invoked action is a declarative fileuploadaction (wire type fla, such as Extension Management's "Upload Extension..."), which uses a different protocol this tool does not serve.

Provide the file as either path (an absolute path to a local file) or base64 (inline content, with fileName).

The response reports the uploaded fileName, sizeBytes, the target formId, and any dialogsOpened the AL code raised in reaction to the file (e.g. a validation error for a bad file — respond to those with bc_respond_dialog, or re-read the page with bc_read_data to see the imported rows). This tool is for pushing a file TO BC; to retrieve files FROM BC (reports, "Open in Excel"), use bc_run_report / bc_execute_action, which return downloads[].

Example (local path): { "pageContextId": "session:page:9650:ab12", "path": "C:/tmp/layout.docx" } Example (base64): { "pageContextId": "session:page:9650:ab12", "base64": "UEsDBAo...", "fileName": "layout.docx" }

Input Schema

Name	Required	Description
`path`	No	Absolute path to a local file to upload. Provide exactly one of `path` or `base64`.
`base64`	No	Base64-encoded file content, as an alternative to `path`. Provide exactly one of `path` or `base64`.
`formId`	No	Override the target dialog form id. By default the open FileUploadForm dialog on the page is used. Pass the form id from bc_execute_action's dialogsOpened to target a specific upload dialog; it must be a FileUploadForm.
`fileName`	No	File name BC should see (e.g. "extension.app"). Required with `base64`; defaults to the basename of `path`.
`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.
`pageContextId`	Yes	Page context ID of the host page whose upload action you just invoked (e.g. page 9650 after "Import Layout"). The open FileUploadForm dialog on that page is targeted automatically.

Output Schema

Name	Required	Description	Default
`formId`	Yes
`success`	Yes
`fileName`	Yes
`sizeBytes`	Yes
`replaySafe`	Yes
`dialogsOpened`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.4.7Nov 5, 2026
- addedOutput schema / properties / dialogsOpened / items / properties / pageContextId
```
Added value: +{
+  "type": "string"
+}
```
- changedOutput schema / properties / dialogsOpened / items / required
```
Previous value: -[
-  "formId"
-]New value: +[
+  "formId",
+  "pageContextId"
+]
```
Addedv2.0.0Oct 15, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: it discloses the multipart POST to BC's DynamicFileUploadHandler over the existing authenticated session, that the dialog is closed afterwards and AL code resumes, and that a missing dialog would otherwise yield a silent HTTP 200 no-op. It also explains the failure mode this tool forces instead of silent byte discard and summarizes what the response contains.

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?

Well front-loaded: the two-step flow is stated in the first sentence before the mechanics, and the two usage examples make the call shape concrete. It is long and repeats some schema content (path/base64 exclusivity), but almost every paragraph carries new decision-relevant information.

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?

Covers the prerequisite step, the targeting default and override, the failure conditions specific to this protocol, how to react to dialogsOpened (bc_respond_dialog / bc_read_data), and the alternative for downloads. With an output schema present, it does not need to enumerate return values, and it points to the right follow-up tools for anything after the upload.

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

Parameters3/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 all six parameters including the path/base64 mutual exclusion, fileName defaults, formId targeting and the operationId/replay semantics. The description restates the path-or-base64 choice and adds only modest framing (pageContextId must come from the page whose action was just invoked), which is consistent with the baseline when the schema carries the weight.

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 ("Upload a local file into a Business Central file-upload dialog") and explicitly scopes it as pushing a file TO BC, naming the siblings used for the opposite direction (bc_run_report / bc_execute_action returning downloads[]). An agent can distinguish it from every sibling without opening a schema.

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?

Gives an explicit two-step protocol with the prerequisite action (bc_execute_action, e.g. "Import Layout" on page 9650) and the pageContextId handoff, plus a clear when-not: no FileUploadForm open, the action opened an error dialog, or the action is a declarative fileuploadaction. The retrieve-files alternative is named explicitly.

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