bc_api_invoke
Runs Business Central API write actions: create, modify, delete records, or post documents. Pass the action name and parameters to apply changes with BC's own validation.
Instructions
Runs a Business Central API action that changes data: Create_* (insert a record), Modify_* (update one), Delete_* (delete one), or a bound/unbound action such as posting a document. Get the action name from bc_api_search and its exact parameters from bc_api_describe, then pass them as the "parameters" object. Create and Modify return the record as BC saved it, including its new "@odata.etag"; Delete returns no result.
Modify needs the record's key ("id") and "If-Match" set to its current "@odata.etag" (read it with bc_api_list); a stale etag is refused with API_ACTION_ERROR "Request_EntityChanged" — re-read and retry. BC applies its own validation and business logic; a rejection is API_ACTION_ERROR with BC's message and nothing is changed. Write actions exist only for API objects an admin enabled with those permissions in BC's MCP Server Configuration.
Pass an operationId to make a retry safe: the same id replays the first result instead of running the action again. replaySafe is true for Modify and Delete (a repeat is refused by BC: stale etag, or record gone) and false for Create and bound actions (a repeat would create or post again). When NOT to use: to read (bc_api_list), or for changes that need the UI's dialogs and pages (bc_open_page, bc_write_data, bc_execute_action). Runs on BC's own MCP server (BC 29+); needs no web-client session.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| company | No | Company to run in (exact, case-sensitive name from bc_list_companies). Defaults to the current session company, then BC_ODATA_COMPANY, then the user's default company in BC. | |
| actionName | Yes | A Create_*, Modify_*, Delete_* or bound/unbound action name from bc_api_search. List_* actions go through bc_api_list. | |
| parameters | Yes | The action's parameters as an object, exactly as bc_api_describe's schema names them. Create: the field values, e.g. { "displayName": "Contoso" }. Modify: the key ("id"), "If-Match" with the record's current "@odata.etag" (from bc_api_list), and the fields to change. Delete: the key. Bound action: the key plus the action's own parameters. | |
| 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
| Name | Required | Description | Default |
|---|---|---|---|
| result | No | ||
| company | Yes | ||
| actionName | Yes | ||
| replaySafe | Yes |