Skip to content

Written for: For developers

Build a Data App with your AI agent

11 min read · Updated 18 Nov 2026

This page is for you and for the AI agent you connected to Astrato over MCP. Point your agent here, or let it find this page on its own: the Astrato connector names it before the agent’s first call. Ask for an app in a sentence, such as “build me a trading dashboard on the Fernhill layer”, and the steps below turn that into a finished, designed page rather than a few default charts.

Agents: follow this page in order. It is short on purpose; each step links to the guide with the detail. Read a linked guide when you reach that step. Read every page in full: this one from the connector (resources/read nash-mcp://guides/build-a-data-app), and the others from their plain-text copies listed in llms.txt, with curl when you have a shell. A web fetch that summarises a page drops the commands and rules these steps rely on.

Ask in one message, offering choices, and go on with sensible defaults for anything left unanswered:

  1. Which semantic layer, if more than one fits. List them with astrato_semantic_layer_list, or with astrato semantic-layers list --name <words> from the CLI.
  2. Who reads the page and what they decide with it, such as “the trading team, each Monday”.
  3. The look: their brand colours, logo and fonts, or a direction in a few words, such as “calm and editorial” or “a dark wall screen”. With neither, you design it; see Design the look.

Do not ask about chart types, layout or which measures to show. Work those out from the layer.

Check your access first. Over MCP, call astrato_get_context once. If it lists tools in toolsRequiringMissingScopes, tell the user straight away which ones will fail and ask them to reconnect the Astrato connector; retrying does not help. With the CLI, astrato semantic-layers describe <id> still reads the layer meanwhile.

Before planning the page, read the layer, as Read the layer before you build describes. Over MCP, use the semantic layer tools; with the CLI, astrato semantic-layers describe <id> prints its stored measures and dimensions with their descriptions, and each view’s columns. Read:

  • its measures and which of them have a stored comparison, such as a year-on-year growth measure; only those can carry a change on a KPI card;
  • its date axes, such as a monthly order date, for trends;
  • the dimensions people slice by, and its saved business questions.

Then check the data itself with a few small queries or by running saved questions: the date range it covers, whether the latest period is still partial, and the values of the dimensions people filter by. A partial latest month explains a drop at the end of a trend; say so on the chart rather than letting it read as a fall.

Build each view on a business question. List the layer’s saved questions (astrato_semantic_layer_list_questions) and base each view on one that answers exactly what it shows: reuse a saved one, or save the one the view needs when you may author the layer. Give the chart its question’s name as question, so a reader can pin it and follow its next questions. If the user asks for an app without business questions, advise against it first: its views would drift from the layer’s definitions and could not be pinned or reused. Build without them only if the user still asks, and say which views have none.

The business question tools, such as astrato_semantic_layer_list_questions, are offered only where business questions are switched on for the organisation. If your connection has none of them, build each view from the layer’s stored measures and dimensions instead, do not try to save questions another way, and say in your reply that the views have no business questions because the feature is not available.

Plan from what the data supports: a headline finding, KPI cards for the measures that matter most (two to four, each with its stored comparison where the layer has one), one hero view and the supporting views that answer the reader’s questions. See Cover what the data supports.

  • You can run commands and write files (Claude Code, Cursor, Codex and similar): build locally with the Astrato CLI. Update it first with npm install -g @astrato-io/cli@latest. Start from a Vite vanilla-ts project (npm create vite@latest <directory> -- --template vanilla-ts): a React scaffold’s src/App.tsx and src/main.tsx collide with the template, which then writes nothing. In it, run astrato init . --semantic-layer-id <id> --template dashboard, install the packages its output lists, then run astrato dev. If astrato init --help lists no --template, tell the user their CLI predates the dashboard starter. That init writes only astrato.json and .gitignore: there is no src/kit.tsx, src/figures.ts or src/look.tsx, so the step 5 code does not resolve. Build the same hierarchy yourself on the runtime and @astrato-io/visualizations, following Compose an app. Either way, draw every chart with @astrato-io/visualizations, as Compose an app requires: a missing starter is not a reason to draw charts in SVG, canvas or CSS.
  • You cannot run commands (a chat client): build in App Builder with the astrato_app_builder_* tools.

In App Builder, or with --template dashboard, the app starts from the same starter: src/kit.tsx mounts charts and filters, src/figures.ts queries live figures for KPI cards and the headline, src/look.tsx and src/look.css are the finish, and src/styles.css holds the design tokens. With the CLI, --template dashboard also writes an src/App.tsx already framed as in step 5, with the layer’s names left as TODOs. The starter uses React’s automatic JSX runtime: keep "jsx": "react-jsx" in tsconfig.json.

The starter’s tokens are greys, so a page that keeps them looks unfinished. Designing this app’s look is your job, and no two apps should look alike. Start from the user’s brand when they gave one. Otherwise derive the look from the app itself: note in a line each the subject and its world, who reads the page and how often, and the shape of the data. Then decide the ground (light, dark or tinted), the one accent that leads, the heading voice and how dense the page is. A finance pack, a warehouse wall screen and a marketing review should each look like their subject. Choose a style and Theming explain the choices and each token.

Set the look as tokens in src/styles.css: everything in the finish reads them. Change the values in the starter’s own :root block rather than adding a second one: where two blocks set the same token, the later one wins, so the starter’s --font-display: var(--font-body) would undo a heading face set earlier. These are the tokens a look sets; the values are placeholders to replace, not a look to reuse:

:root {
--page: #rrggbb; /* the page ground */
--surface: #rrggbb; /* cards and filters */
--line: #rrggbb; /* borders and axis lines */
--ink: #rrggbb; /* text */
--muted: #rrggbb; /* secondary text and axis labels */
--accent: #rrggbb; /* the colour that leads: headline figures, the hero line, bars */
--delta-up: #rrggbb; /* a change that is good news */
--delta-down: #rrggbb; /* a change that is bad news */
--series-1: #rrggbb; /* --series-1 to --series-4: a chart split by a second dimension */
--series-2: #rrggbb;
--series-3: #rrggbb;
--series-4: #rrggbb;
--font-display: 'Your heading face', serif; /* the headline voice */
--look-radius: 12px; /* card corners */
/* On a dark ground, cast shadows in black, not in the light --ink. */
--look-shadow: 0 1px 2px rgb(0 0 0 / 8%), 0 18px 40px -22px rgb(0 0 0 / 30%);
}

Keep the starter’s other tokens, such as --gap and the text sizes, unless the look needs them changed. The finish’s cards read --look-radius and --look-shadow, not the starter’s --radius and --panel-shadow. Give colours as six-digit hex values: charts read them through operations, which accept nothing else. Override anything else in your own CSS; the finish’s selectors carry no specificity, so your rules win.

Whatever the look, keep the page’s hierarchy. A reader takes it in in this order, and each level is visibly larger or stronger than the next:

  1. The headline: the finding, in one sentence, the largest text on the page.
  2. The headline figures: KPI cards for the measures that matter most.
  3. One hero view: the chart that shows the finding, the largest chart on the page.
  4. Supporting views: smaller, answering the reader’s next questions.
  5. The source, at the foot.

Do not flatten it: no grid of equal tiles, no second hero, no page without a headline. Frame the page with the finish in src/look.tsx, whose pieces carry this hierarchy: Masthead, KpiRow, and a Board with one Panel hero. They draw from your tokens, and you can restyle any of them in your CSS. Start from the finish lists every piece.

import type { AppContext } from './astrato';
import { cellNumber, useFigures } from './figures';
import { Chart, FilterHost, FilterRow, SelectionBar, useChart } from './kit';
import {
Board,
chartLook,
describeChange,
filterLook,
formatNumber,
KpiCard,
KpiRow,
Masthead,
Page,
Panel,
} from './look';
const GROUP = 'dashboard';
const USD = { style: 'currency', currency: 'USD' } as const;
/** A dropdown filter on one field, styled from the tokens. Name the view when several views have
* a column with this name: key(field, view) refuses to guess. */
function Filter({ astrato, id, field, view }: { astrato: AppContext; id: string; field: string; view?: string }) {
const { hostRef } = useChart({
astrato,
id,
group: GROUP,
view,
definition: (key) => ({
version: 1,
type: 'filter',
data: { field: { ref: 'field', fieldKey: key(field, view) } },
presentation: { mode: 'dropdown', searchable: true, quickSelect: false, responsive: false },
}),
operations: () => filterLook(),
});
return <FilterHost id={id} hostRef={hostRef} />;
}
export function App({ astrato }: { astrato: AppContext }) {
// Live figures, filtered by the page's selections and re-queried when they change. The stored
// growth compares the months on its date axis, so the revenue beside it is summed over the same
// months: a plain total would cover every order on record and the sentence would be false.
const comparison = useFigures(astrato, ['Net Revenue YoY Growth'], { group: GROUP });
const months = useFigures(astrato, ['Net Revenue'], { group: GROUP, dimensions: ['Order Date (Month)'] });
const growth = comparison.values['Net Revenue YoY Growth'];
const cells = months.rows.map((row) => cellNumber(row[1])).filter((cell): cell is number => cell !== undefined);
// No numbers at all is no value, not zero.
const revenue = months.state === 'ready' && cells.length > 0 ? cells.reduce((sum, cell) => sum + cell, 0) : undefined;
// Ready only when both are: a new value beside the previous selection's change would be false.
const state =
comparison.state === 'error' || months.state === 'error'
? 'error'
: comparison.state === 'ready' && months.state === 'ready'
? 'ready'
: 'loading';
return (
<Page>
<Masthead
eyebrow="Fernhill Outdoor · Trading"
title={
revenue === undefined ? (
'How is Fernhill trading?'
) : (
<>
Net revenue of <em>{formatNumber(revenue, USD)}</em>, <em>{describeChange(growth).text}</em> on the same
months last year
</>
)
}
standfirst="Revenue over the months on the order-date axis, and its mix across categories."
>
<FilterRow>
<Filter astrato={astrato} id="filter-channel" field="Sales Channel" />
<Filter astrato={astrato} id="filter-category" field="Category" view="Products" />
</FilterRow>
<SelectionBar
selections={astrato.app.client.services.selections}
group={GROUP}
availableFields={astrato.availableFields}
fieldLabel={(key) => astrato.availableFields.find((field) => field.fieldKey === key)?.name ?? key}
/>
</Masthead>
<KpiRow label="Headline figures">
<KpiCard
id="kpi-revenue"
label="Net revenue"
value={revenue}
format={USD}
change={growth}
compare="vs same months last year"
state={state}
onRetry={() => {
comparison.retry();
months.retry();
}}
trend={
<Chart
astrato={astrato}
id="kpi-revenue-trend"
group={GROUP}
placeholder="line"
operations={(item) => chartLook('line', 'trend', { measures: [item('value')] })}
definition={(field) => ({
version: 1,
type: 'line',
data: {
dimensions: [{ ref: 'month', fieldKey: field('Order Date (Month)') }],
measures: [{ ref: 'value', fieldKey: field('Net Revenue'), dataPointShape: 'circle' }],
},
})}
/>
}
/>
</KpiRow>
<Board>
<Panel hero title="Net revenue by month" subtitle="USD after discounts, against the same month last year">
<Chart
astrato={astrato}
id="revenue-by-month"
group={GROUP}
placeholder="line"
operations={(item) =>
chartLook('line', 'hero', { measures: [item('value'), item('prior')], date: item('month') })
}
definition={(field) => ({
version: 1,
type: 'line',
data: {
dimensions: [{ ref: 'month', fieldKey: field('Order Date (Month)') }],
measures: [
{ ref: 'value', fieldKey: field('Net Revenue'), dataPointShape: 'circle' },
{ ref: 'prior', fieldKey: field('Net Revenue (Prior Year)'), dataPointShape: 'circle' },
],
},
})}
/>
</Panel>
<Panel title="Net revenue by category" subtitle="USD after discounts">
<Chart
astrato={astrato}
id="revenue-by-category"
group={GROUP}
placeholder="bars"
operations={(item) =>
chartLook('bar', 'support', { measures: [item('value')], dimension: item('category') })
}
definition={(field) => ({
version: 1,
type: 'bar',
data: {
dimensions: [{ ref: 'category', fieldKey: field('Category', 'Products') }],
measures: [{ ref: 'value', fieldKey: field('Net Revenue') }],
},
sorting: [{ by: 'value', direction: 'desc' }],
})}
/>
</Panel>
</Board>
<p className="look-source">Source: Fernhill Outdoor semantic layer</p>
</Page>
);
}
  • Headline: the finding, built from useFigures so it stays true for every selection. Wrap its figures in <em>. Put a value beside a comparison only when both cover the same period: query the value by the comparison’s date axis and add up the rows, as above, when the measure is additive. See Lead with a business story.
  • KPI cards: give a measure with a stored comparison its change, queried as a total as above: a stored year-on-year measure needs no date dimension to compare the selected scope with its comparison period. Never compute a change in the app. For a measure the layer stores no comparison for, leave it out of the KPI row, and your reply says which comparisons the layer lacks. When the comparison exists but returns nothing for the selection, keep the card: it shows “No comparison”. Pass goodWhen="down" for a measure such as cost. See KPI card.
  • Comparison labels: compare names what the stored comparison measures against. Take it from the measure’s description, such as “vs same months last year”; never write “vs last period” when you do not know which period that is.
  • Charts: one hero panel, then supporting panels. Start every bar and line chart’s operations with chartLook, passing its measures, and add your own operations after it. Pass the date dimension as date so months read “Oct 25” rather than raw dates; draw a supporting series over time as a line, whose months stay level. Supporting bars are drawn horizontally so long names stay readable; sort them by value in the definition, show at most about ten, and pass categories when there are more than six so their labels fit. Pass a category as dimension to leave out its empty (null) row. Numbers keep the measure’s own format; pass compact: true only for large counts with no unit. A line with a second measure, such as last year, draws it dashed and unfilled. Line measures need dataPointShape.
  • Filters: a dropdown filter for each of the two or three dimensions people slice by, in the masthead, styled with filterLook(), as above. Field names repeat across views (a region on orders and on customers), so name the view as the example does. See Filters and selections and Filter bar.
  • Titles: sentence case, “Measure by Dimension” or the question, with unit, period and scope in the subtitle. A chart follows the page’s selections, so never write a fixed scope such as “all channels” in its subtitle. End the page with its source.

Open the app with astrato dev, or inspect the Builder preview, and check:

  • the tokens are set: nothing on the page is still grey;
  • every chart has drawn, in the accent rather than default colours, and the console shows no “mounted without some settings”;
  • clicking a bar or a month, then Apply, updates the selection bar, the headline and the KPI cards;
  • loading, empty and error states read clearly.

Then work through Verifying an app, which has the full checklist, at least its Final checks. In your reply, name the finding the page leads with, the look you chose, anything you left out and why, and the checks you did not run. Name every step of this page you did differently, such as charts not drawn with @astrato-io/visualizations or views not based on business questions, and why.

Publishing shares the app, so do it only when the user asks. In Builder, the user publishes from the editor. With the CLI (Publish an app):

  1. Create the publication once with astrato publications create . --name <name> --idempotency-key <key>.
  2. Before every publish or publications update, run astrato publications get <id> and pass its version as --expected-version.
  3. Publish with astrato publish . --publication-id <id> --expected-version <version> --idempotency-key <key>.

Make an app public only when the user asks for that too, and confirm it with them first: anyone with the link sees its data. Ask whether the link should expire, then run astrato publications update <id> --expected-version <version> --audience public, adding --expire-at <utc> for an expiry. If the result carries publicDataWarning, the semantic layer or its data connection is still closed to public viewers, and the CLI cannot open it: tell the user to open it in the app’s Public access tab, as Share an app with people outside your team describes, where Data for public viewers must show both as Open to public viewers. Then open the link in a private browser window, signed out of Astrato, and check that the numbers load. Access changes can take up to five minutes to reach viewers.