Skip to content

Written for: For developersUsing Astrato instead? Read the product guide

Data Apps over MCP

10 min read · Updated 17 Nov 2026

This page is for developers and agents working with Data Apps through the Astrato MCP server. What a person does in the product is in Manage Data Apps and App Builder.

MCP and Nash manage publications. They do not build app code, upload files or publish content. Contract 6.0.0 removes the prepare/complete publishing tools; reconnect and refresh tool discovery if a client cached the earlier schema. Use the CLI publication workflow for a local project, or the Builder Publish action for a saved Builder project.

The astrato_dashboard_freeform_* tools and the dashboard-freeform resource type name Data Apps; dashboard-canvas names a workbook’s Canvas dashboards.

Tool Scope Purpose
astrato_dashboard_freeform_create publication:write Reserve an unpublished publication for a semantic layer
astrato_dashboard_freeform_update publication:write Change name, labels or hosting; when publication access settings are enabled, also audience, expireAt and embedding
astrato_dashboard_freeform_list publication:read List Data Apps the current user can view
astrato_dashboard_freeform_get publication:read Read state, URL, version and optional hosting diagnostics
astrato_dashboard_freeform_unpublish publication:publish Disable delivery while retaining the current content
astrato_dashboard_freeform_delete publication:write Remove a Data App from the catalog and disable delivery
astrato_management_access_describe publication:manage-access Describe supported principals and permissions
astrato_management_access_list publication:manage-access List direct user, group and tenant grants
astrato_management_access_grant publication:manage-access Create or refresh one direct grant
astrato_management_access_revoke publication:manage-access Remove one direct grant

Data App metadata and publish-state mutation tools take expectedVersion. Read the app first, pass its returned version, and read it again before retrying if another change causes a version_conflict. Access-grant changes do not change the publication version.

Creation takes an idempotencyKey. Reuse the same key when retrying a request whose result was lost; use a new key for a new target. For content publishing and interrupted uploads, follow the CLI publication workflow.

Each successful publish pins the semantic layer’s current published revision and its data connection. Later semantic-layer draft changes do not silently change an existing Data App. Publishing the semantic layer again does break it. An app is servable only while its pinned revision is still the layer’s current published revision; after a later publish its bootstrap, model reads and data-token requests all fail with 409 app_unavailable, and anyone opening its link in a browser tab sees This app needs to be republished instead of the app. Publish each affected Data App again after publishing its layer — see Hosted app sessions.

Publishing the Data App again replaces both its current files and pinned data binding. Astrato does not keep deploy history for rollback; restore an earlier revision in your source repository, rebuild it, and publish it again. For a release checklist and step-by-step rollback, including App Builder’s source versions, see Go live: publish, versions and rollback.

Read a Data App with includeHosting: true to discover available locations, its data-node profile, default location and prerequisite warnings. This also requires read access to its semantic layer. Update hosting with { "mode": "data-node" } to follow the data node, or { "mode": "custom", "deploymentBindingId": "<id-from-hostingStatus.locations>" } to select a returned location. Hosting updates require both manage and publish permissions, plus publication:publish for OAuth in addition to publication:write. Use the current expectedVersion.

The MCP astrato_dashboard_freeform_update tool accepts audience, expireAt and embedding: { enabled, allowedDomains } with expectedVersion. Add grantPublicDataAccess: true with audience: "public", or on its own for an app that is already public, to grant anybody read access on the app’s semantic layer and data connection first. The response lists each under publicDataAccess as granted or already-open; one already open is left as it is. Sent on its own, it changes neither the app nor its version, so send it alone to re-check an app that is already public: sending audience: "public" again with it saves the app and moves its version. Each grant needs permission to manage that resource’s access, and OAuth clients also need publication:manage-access. If a grant is refused, the app is not changed and the error names any resource the call had already opened, which stays open. On a data connection that cannot serve public viewers, as described above, both audience: "public" and grantPublicDataAccess fail with public_data_connection_per_viewer and nothing is granted.

astrato_dashboard_freeform_list and astrato_dashboard_freeform_get return republishRequired: true for an app that needs publishing again, as the Library marks it.

An OAuth client, such as the CLI or an MCP client, needs these scopes as well as the signed-in user’s own permissions. A personal access token carries every scope an external client can hold.

Task Scopes
View a hosted Data App (viewer sign-in) publication:read, schema:read, data:access-token
List and read Data Apps publication:read
Create, rename, label or delete a Data App publication:write
Publish or unpublish, or set or clear a cover image publication:publish
Change hosting publication:write and publication:publish
Change audience, expiry or embedding, or grant and revoke access publication:manage-access
Run a Business Workflow from a Data App (viewer) data:action, where Astrato has turned it on

Publication summaries leave out Delete when the grant lacks publication:write, even when the user may delete. A viewer’s grant cannot delete a publication, through the deletion tool or otherwise.

This optional MCP workflow lets an external AI agent work on source saved in Builder. Builds and preview interactions still run through your connected Builder browser. Use the Builder project and its tools; the local CLI setup below does not apply to this workflow. Choose either Builder execution or local CLI builds for a project and keep using that workflow; see using both approaches.

External agents can use these MCP tools:

  • workspace:read: astrato_app_builder_list, astrato_app_builder_read and astrato_app_builder_versions.
  • workspace:write: astrato_app_builder_open, astrato_app_builder_edit, astrato_app_builder_restore and astrato_app_builder_execute.

For the open app in Builder, Nash can omit appId on read, edit, versions, restore and execute after checking your access. Explicit IDs still target the specified app and keep all applicable checks. External MCP callers must provide each tool’s required appId.

The signed-in caller must own the project. Use astrato_app_builder_list to find an existing app by name. astrato_app_builder_open also creates one: omit appId and pass name, semanticLayerId and an idempotencyKey. Creation is refused unless all three are present, and semanticLayerId is ignored when appId opens an existing app. External MCP returns a full browser URL. Open that URL while logged in before requesting changes. If Builder shows Editing paused, choose Resume editing, then tell the agent to continue. The agent must continue through the same Builder project and its saved source.

Publishing is not among these tools. It is the Publish action in the editing browser, so an agent’s work reaches a publication only when you publish it yourself.

astrato_app_builder_read returns up to 12,000 characters of content per call. To continue a file, send that one path with its nextOffset; an offset of 0 reads every path from its start. In astrato_app_builder_edit, a patch’s oldText must match the file exactly once, whitespace included. Edits apply in order, and one refused edit applies none of them: the refusal names each patch that missed and what differs, so correct those and send the whole call again.

Builder builds every saved revision from its saved npm lock, so an edit cannot change package.json dependencies that package-lock.json does not record, or remove the lock: it is refused as dependency_lock and nothing in it is applied. Add, change or remove packages with an npm command through astrato_app_builder_execute, such as npm install --ignore-scripts <package> or npm uninstall <package>, which saves both files together. Other package.json changes are edits as usual.

Edits, restores and executions send the lease generation and the source revision, as expectedRevision, from the agent’s latest source read or from its latest edit, restore or execution result: each of those returns generation and revision, so the agent can continue without reading source again. astrato_app_builder_restore also takes the revision to restore. A result with no generation, such as one saying execution finished but its details were lost, means read source first. The server checks both values on every call, however the agent got them. Guess neither value. The lease renews while Builder stays open, however long the agent works. Only these refusals report a problem with the editing session:

  • lease_lost: the generation belongs to an earlier Builder editing session, for example one from before you reloaded Builder. The agent stops and waits until you ask it to continue.
  • invalid_generation: the agent sent a generation it was not given. It reads source again. If the returned generation matches the one it read earlier, or it had not read one, it retries with that generation. Otherwise Builder editing restarted: the agent stops and waits until you ask it to continue.
  • waiting_for_browser: no Builder tab is editing this app yet, because it is not open or Builder is still preparing the app. This does not mean editing was lost. The refusal includes the app URL: open it if it is not open. Editing connects automatically once Builder shows the app, with no separate step to start editing.

A stale expectedRevision is refused as revision_conflict. The source changed, not the editing session, so the agent reads source again and reapplies its change.

If the app’s source changes while an execution is still waiting or running, for example because you saved an edit in Builder, the execution ends with execution_superseded and nothing from it is saved. The agent reads source again and reruns the execution if it still needs it.

A source read before Builder has prepared a new app returns no source. For an external agent it returns status: waiting_for_browser with the app URL: open it if you have not, and the agent reads again once Builder shows the app. When Nash works from that app’s own Builder page, the read waits briefly for Builder and then returns status: opening, and Nash reads again instead of asking you to do anything. If Builder is still preparing the app after four minutes, Nash stops and asks you to send a message once Builder shows it.

To test a path through the preview in one operation, an agent sends action.type sequence to astrato_app_builder_execute: up to six clicks, fills, scrolls, navigations or viewport changes in order, then one inspection. A step names its control by the ref from the latest inspection or by its exact label, ignoring case, with role if several controls share it. A label reaches a control that appears only after an earlier step, such as an option in a menu; it replaces earlier refs, so later steps use labels too. Each step waits for the app’s data as a single interaction does. The sequence stops at the first step that fails, and the result reports failedStep, stepsCompleted and stepsTotal with the preview as it stands. A sequence changes only the preview, never saved source, and is not replayed automatically. It returns one screenshot, so comparing two states takes two sequences.

The optional request on astrato_app_builder_open carries up to 8,000 characters of app intent and agreed choices in its result. External MCP clients retain their own conversation and explicitly continue through the tools after the browser connects. A read result with status: waiting_for_browser means Builder has not prepared the app yet: open the returned URL if it is not open, and read again once Builder shows the app. Reading source again does not prepare it. Starting or continuing a request does not change published app artifacts; publishing remains a separate explicit action.

The test copy for an App Builder app asks an assistant to create a second app and copy the live app’s source into it.

The assistant finds Sales app with astrato_app_builder_list and creates the copy with astrato_app_builder_open. That call returns the new app’s ID, its address and whether App Builder has it open yet:

{
"appId": "<new-app-id>",
"url": "https://<your-astrato-address>/web/app-builder/<new-app-id>",
"status": "waiting_for_browser",
"revision": null,
"generation": null
}

waiting_for_browser means no App Builder tab has prepared the app yet, so the assistant asks you to open the url. Once you have, it reads Sales app’s files and writes them into the copy. Each astrato_app_builder_edit returns the copy’s new revision, for example { "appId": "<new-app-id>", "revision": 2, "generation": 1 }. You are done when the assistant reports the files copied and the revision, and the test copy’s Preview in App Builder shows the same app as Sales app.

For each release, save the change in the live app’s project (saving does not change what is published), have the assistant copy the saved source to the test copy again, publish the test copy and test it, and then publish the live app. See External agents using App Builder.