MCP contract changes

Contract 8.54.0 imports Snowflake verified queries as business questions through astrato_semantic_layer_preview_snowflake_view_import and astrato_semantic_layer_import_snowflake_view. A query that does not map is skipped with a verified_query_not_supported diagnostic, and the summary gains businessQuestions and skippedQuestions. See Import a Snowflake semantic view. Tool names, input schemas, scopes and gates do not change.

Contract 8.53.0 adds delimiter to aggregate measure inputs and patch.aggregateOptions.values for LISTAGG / VALUE_LIST. An empty string joins values without separation; null restores comma and space. Existing calls that omit it retain their behavior. Refresh cached tool schemas. See Value list separators.

Contract 8.52.0 refuses an astrato_app_builder_edit call that changes package.json dependencies without a matching package-lock.json, or removes the lock, with dependency_lock, and applies nothing in it. Add, change or remove packages with an npm command through astrato_app_builder_execute, as described in App Builder. A refusal does not apply when the source already mismatches and the edit leaves both dependency declarations unchanged.

Contract 8.50.0 adds the feature-gated astrato_semantic_layer_run_data_action, which runs one published data action with named parameter values. It runs the published version of the layer, never a draft. Call it without confirm to get a preview and run nothing; send confirm: true and the preview’s previewToken only after the user approves. The run is refused if the action, its arguments or the published layer differ from the preview. The engine applies the caller’s own data permissions and identity. It needs the data:query and sl:write scopes. Never run it again to retry an interrupted run or an outcome with effects: unknown; check the data first. Reconnect to refresh cached schemas.

Contract 8.49.0 returns generation beside revision from astrato_app_builder_edit, astrato_app_builder_restore and astrato_app_builder_execute, so an agent sends those values on its next call rather than reading source first. astrato_app_builder_execute also accepts action.type sequence: up to six preview interactions in order, then one inspection, as described in App Builder. A clickAt is sent on its own. Existing calls keep working; refresh cached tool schemas.

Stability: preview. Nash tool contract 6.69.0 refuses a measure grouped by a dimension its view cannot reach, and returns Builder app links on the configured public address or the browser-reachable host the request arrived on. Contract 6.61.1 corrects the permission grantPublicDataAccess says it needs, and says to send it alone to re-check. Contract 6.61.0 returns a refusal’s code and status beside its message. Contract 6.59.0 lets astrato_dashboard_freeform_update open a public Data App’s data to public viewers with grantPublicDataAccess. Contract 6.58.0 adds an optional correlation ID check before bug drafts in the Support portal. Contract 6.57.0 adds astrato_semantic_layer_set_visibility, which turns a layer’s “Visible to everyone” on or off. Contract 6.56.0 puts a Top N’s Others row where its position says when the question has an orderBy, runs a stored period comparison over a window on a Time Axis the query does not select, and refuses a comparison that would silently drop a stored one, and date arithmetic in a result formula; validating a layer reports a stored question of either shape as an error that blocks publishing. Contract 6.50.0 lets astrato_semantic_layer_list look up one layer by semanticLayerId, to name a layer known only by its id. Contract 6.17.0 adds AI Support tools to in-product Nash when support is enabled; these tools are unavailable to external MCP clients. Contract 6.16.1 lets Nash import a CSV attached in the chat panel. Contract 6.11.0 adds query context and optional replay capture to data preparation and execution. Reconnect to refresh cached tool schemas and instructions.

Contract 8.15.0 keeps only the latest versions’ changes in the server instructions and in astrato_get_context. The complete history is the resource that toolContract.migrationHistoryUri names, read with resources/read. astrato_get_context also reports baseline scopes a connection lacks. Tool names, arguments, scopes and authorization are unchanged. Reconnect to refresh instructions.

Contract 7.4.0 adds MCP 2026-07-28 URL elicitation for secure browser authorization across remote data tools. Auth determines compatible authorization options; missing configuration returns an actionable error without creating a pending action, and discovery failures remain upstream errors. Confirmed browser authorization resumes eligible reads; mutations require checking current state and a fresh request. Clients without URL elicitation receive a secure browser link. OAuth connection forms complete sign-in before validation and saving. Accepting an elicitation request does not prove authorization completed. Tool names, arguments and scopes are unchanged.

Contract 7.2.0 adds behavior annotations to every MCP tool: title and readOnlyHint, plus destructiveHint for tools that write. Read-only tools declare readOnlyHint: true; tools that only create new resources or restorable versions declare destructiveHint: false; tools that change, replace, remove, disable or revoke existing resources declare destructiveHint: true. Clients may use these hints when asking for confirmation; authorization is unchanged. Reconnect to refresh tool listings. Tool names, arguments and scopes are unchanged.

Contract 7.0.0 intentionally removes astrato_app_builder_runtime and astrato_app_builder_update_runtime for new npm-based Builder apps. Use explicit npm commands through astrato_app_builder_execute for library changes, then build and inspect. Existing apps are not migrated; saved data and published files are unchanged. The guide action is also removed. In-product Builder Nash uses internal web_fetch; external agents use their own web fetch, starting at https://docs.astrato.io/llms.txt and following the returned links. Reading documentation needs no app source or editing lock. Documentation does not prove compatibility with installed packages. Refresh cached tool schemas.

Contract 6.8.0 describes how a Business Question filter is written, with date examples, in the query schemas; no schema changes. Contract 6.4.0 adds CSV import into a data connection that allows writes. Contract 6.0.0 removes the Freeform prepare/complete publish tools. Use the CLI to build and publish app content. MCP creates explicitly unpublished targets and manages metadata, hosting, lifecycle and access; reconnect to refresh cached tool schemas.

Contract 8.45.0 words suggested questions for readers: names, question text and ids from astrato_semantic_layer_suggest_questions and the related path of astrato_semantic_layer_create_next_questions read like Top 10 Product Names by Net Revenue, and forms that read the same count once. Stored questions keep their names, and no schema changes. A create in astrato_semantic_layer_commit_authoring_batch takes ifExists inside the item’s change, not on the item.

Contract 8.44.0 makes refusals say exactly what to send. astrato_app_builder_read also accepts offset: 0 with several paths. A refused astrato_app_builder_edit call names each patch that missed and what differs. astrato_data_prepare_query and astrato_data_execute_query show the corrected call when a tool argument is written inside query. Everything accepted before is still accepted.

Contract 8.32.0 returns the complete CREATE SEMANTIC VIEW script as statement from astrato_semantic_layer_export_snowflake_semantic_view when finalize is true, besides attaching it as a .sql file, so a client that cannot open attachments still gets it. To turn several semantic layers into Snowflake semantic views, an agent lists them with astrato_semantic_layer_list and calls the tool once per Snowflake-backed layer; each layer has its own approximations and its own script.

Contract 8.0.0 replaces the feature-gated draft Data Actions shape with an explicit implementation. Parameters use compiler data types, presence-sensitive defaults, nullability and metadata references. Implementations define table bindings or per-dialect native arguments and named SQL statements, with explicit results. Updates replace the implementation atomically; null clears optional metadata. Flat targets, statement lists and identity-source fields from the earlier draft are rejected. Scopes, feature gates and layer permissions are unchanged. Reconnect to refresh cached schemas.

Contract 6.72.0 uses named filter references in the existing filters, resultFilters and associativeFilters slots, including nested branch filters. Use reference: { filter: "Name" } instead of an inline body. Root definitions infer their kind from filters or associativeFilters; there is no type discriminator or singular question filter. This unreleased contract has no migration or compatibility aliases. No tools are added, removed or renamed. Reconnect to refresh cached schemas.

Contract 6.68.0 adds feature-gated data-action list, get, prepare and apply tools. They register writable tables and native procedures in the draft and execute no warehouse mutation. Use exact native schema/procedure names from the catalog. In Nash, successful data-action creates, updates and renames include a link to open the saved registration, labelled Business workflow. The existing workflow-policy tool also accepts the current draft revision to reject stale requests. See semantic-layer documents.

Contract 6.66.0 adds the feature-gated astrato_semantic_layer_set_writeback_mode tool. It stores the Business Workflows policy in the draft and publishes nothing. Reconnect to refresh cached schemas.

Contract 6.12.0 adds sets dimensions: astrato_semantic_layer_apply_dimension_change accepts kind: "sets", whose values are stored set filters, and the questions page of astrato_data_prepare_query lists them under setsDimensions. See sets dimensions for their limits.

Contract 6.9.0 adds stored set filters: list, get, prepare and apply tools, and entitySet, which names one in a Business Question or an astrato_data_execute_query query in place of associativeFilters. The questions page of astrato_data_prepare_query lists them under setFilters. Count a set filter’s members by executing its target field with entitySet and limit: 1, then reading totalRecords.

Contract 5.9.0 gives each pending item of the Snowflake semantic view export a disposition and makes approximating pending items opt-in. Contract 5.8.0 adds optional free-text categories to datasets. Contract 5.7.0 lets astrato_data_browse_connection_catalog list a table’s columns and page every catalog level. Contract 5.6.0 lets astrato_semantic_layer_list find layers by name and by datasource. Contract 5.4.0 adds defaults.allMode to Business Questions, which ranks each dimension on its own in Top N. Contract 5.3.0 lets a keyed Business Question measure selection override its stored measure’s format. Contract 5.2.0 adds datasets — named collections of a layer’s existing dimensions and measures — with list, get, prepare and apply tools. Contract 5.0.0 stores Business Question selections as ordered lists that keep their order, each entry optionally keyed; see Business question YAML. Contract 3.1.0 adds associative filters to stored and unsaved Business Questions, preserving target fields and custom names. Contract 3.0.0 uses orderBy and reference targets for sorting/ranking and adds output projection. Contract 2.9.0 authors advanced calculations on a business question’s measures — a rolling window, a running total or rate, a rank, a partition total, or a comparison against it — partitioned and ordered by the question’s own dimensions. Contract 2.8.0 adds period-over-period authoring: create a Time Axis dimension, then create or update a comparison measure using that axis. Formula changes preserve existing comparison settings; an explicit clear removes them. Contract 2.6.0 authors business questions in a batch, so a set of questions commits as one revision in two calls rather than one call and one revision each; 2.5.0 organizes measures and dimensions into categories — the free-text grouping labels the semantic layer editor files its lists by — adds a dimension patch operation so a dimension is filed without re-sending its definition, and reports the categories a layer already uses so authoring reuses a spelling instead of inventing a near-duplicate; 2.4.0 runs a business question grouped by a drill-down at any of its levels; 2.3.0 added optional query response byte budgets and explicit metadata omissions; 2.2.0 introduced best-effort source context. Retained tools keep the product names introduced in 1.0.0; the query contract replaces the data-query selections payload with a canonical Business Question in query and scoped runtime parameters. Earlier preview names remain unavailable. Remove any cached Astrato tool schemas or instructions and reconnect so the client initializes and lists tools again. Future contract versions follow semantic versioning: major changes can be incompatible, minor changes are additive, and patches remain compatible.