Written for: For developers
Build a Data App with your AI agent
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.
1. Ask the user three things, once
Section titled “1. Ask the user three things, once”Ask in one message, offering choices, and go on with sensible defaults for anything left unanswered:
- Which semantic layer, if more than one fits. List them with
astrato_semantic_layer_list, or withastrato semantic-layers list --name <words>from the CLI. - Who reads the page and what they decide with it, such as “the trading team, each Monday”.
- 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.
2. Read what the layer can answer
Section titled “2. Read what the layer can answer”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.
3. Choose where to build
Section titled “3. Choose where to build”- 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’ssrc/App.tsxandsrc/main.tsxcollide with the template, which then writes nothing. In it, runastrato init . --semantic-layer-id <id> --template dashboard, install the packages its output lists, then runastrato dev. Ifastrato init --helplists no--template, tell the user their CLI predates the dashboard starter. Thatinitwrites onlyastrato.jsonand.gitignore: there is nosrc/kit.tsx,src/figures.tsorsrc/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.
4. Design the look
Section titled “4. Design the look”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.
5. Compose the page with the finish
Section titled “5. Compose the page with the finish”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:
- The headline: the finding, in one sentence, the largest text on the page.
- The headline figures: KPI cards for the measures that matter most.
- One hero view: the chart that shows the finding, the largest chart on the page.
- Supporting views: smaller, answering the reader’s next questions.
- 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
useFiguresso 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”. PassgoodWhen="down"for a measure such as cost. See KPI card. - Comparison labels:
comparenames 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 asdateso 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 passcategorieswhen there are more than six so their labels fit. Pass a category asdimensionto leave out its empty (null) row. Numbers keep the measure’s own format; passcompact: trueonly for large counts with no unit. A line with a second measure, such as last year, draws it dashed and unfilled. Line measures needdataPointShape. - Filters: a dropdown
filterfor each of the two or three dimensions people slice by, in the masthead, styled withfilterLook(), 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.
6. Check it before you hand it over
Section titled “6. Check it before you hand it over”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.
7. Publish when the user asks
Section titled “7. Publish when the user asks”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):
- Create the publication once with
astrato publications create . --name <name> --idempotency-key <key>. - Before every
publishorpublications update, runastrato publications get <id>and pass itsversionas--expected-version. - 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.