Skip to content

Show numbers as a chart

When your agent has numbers to show, post them as a chart instead of a table in text. People hover for values, expand the card, switch between chart types that suit the data and change the colors, the fields and the range. The tool is show_chart, part of the Streams MCP server.

show_chart posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card (older apps, search, push notifications).

  • One chart per call. Several charts are several calls. Put your reading of the numbers in the card’s description or in your own message, not in a second chart.
  • You compute the numbers. Send every value in the call: totals, rates and rollups. The card never queries, fetches or refreshes anything. New data is a new card.
  • Display only. Nothing is answered and nothing comes back. The call returns at once, and viewing or changing the card never starts a turn. The card does not count toward the forms and boards creation limit.
  • All or nothing. If anything is invalid, nothing is posted and the error lists each problem with the path of the field to fix, for example data.measures[0].axes[0].series[1].values. The MCP client may write the same path with dots (data.measures.0.axes.0.series.1.values).
  • Safe to retry. requestId is a UUID you generate once per card. Calling again with the same requestId and the same content returns the card already posted (created: false). The same requestId with different content is refused with 409 chat.chart_request_conflict, and so is a retry after the card’s message was deleted.
  • Rate limit. At most 5 new cards per minute per stream and agent: 429 chat.chart_rate_limited with a Retry-After header and details.retryAfterSeconds. Retries of an existing card do not count, and a deleted card still counts for the minute.
  • Deleting the message removes the card.
Field Type Notes
requestId UUID Generate once per card; reuse it on a retry.
streamId UUID The stream to post in. Your agent must be a member.
threadSessionId UUID, optional Put the card in that thread, by its session id.
replyToMessageId UUID, optional Put the card in the thread of that message. With threadSessionId too, both must name the same thread.
heading string, optional Up to 200 characters. Titles the card and the text caption.
description string, optional Up to 300 characters of plain text under the title. The card shows two lines.
type string The chart the card starts as. It must suit data.kind.
data object All the numbers. See the data kinds below.
defaults object, optional Starting view settings. Any subset of the settings below; Reset returns to them.
allowedTypes array, optional The only types people may switch to. It must include type.

The whole card (everything except the ids) is at most 64 KiB. Text is plain text without control characters. savedSettings is reserved for the server and is refused if you send it.

data.kind Types it can draw
series line, area, bar, barH, stacked, donut, funnel
scatter scatter
gauge gauge
heatmap heatmap
gantt gantt (a timeline)

Choose the type that fits the data: a trend is a line or area, categories a bar or barH (horizontal), parts of a whole a donut or stacked, steps a funnel, one value against a target a gauge.

Pick the data shape first, because it decides the type. Numbers per category or per week are series; two numbers per point are scatter; one value against a target is gauge; a grid of rows by columns is heatmap; work items or phases with a start date, an end date and a status are gantt. Send a schedule as gantt rows, never as a bar chart with dates. Only series cards let people switch type. A scatter, gauge, heatmap or gantt card always stays that type, so a card never turns into a timeline or out of one.

series has measures (at most 4). Each measure is { id, label, rollup, axes }, where rollup (sum, average or last) says how weekly values combine into a month. Each axis (at most 4 per measure) is { id, label, categories, series }:

  • categories are { id, label, date? }, at most 120. Either every category has a date or none does.
  • A dated axis is weekly: the dates are consecutive UTC Mondays as YYYY-MM-DD, oldest first. People can roll weeks up to months, and a week belongs to the month of its Monday. Use sum for counts, average for a rate you already computed and last for a level such as a balance. Never send a rate that needs weighting as a summed measure.
  • series are { id, name, values }, at most 6 per axis, with exactly one value per category. A missing value is null and is drawn as a gap, never as zero.
  • Several measures become the Y choice and several axes the X choice, so send them only when the breakdowns are real.
  • A donut needs one sum series with non-negative values, a funnel one non-negative series, and a stacked chart cannot draw negatives.

scatter is { xLabel, yLabel, points } with at most 500 points { id, x, y, label? }. gauge is { value, target, min, max, label? } with min below max and target between them. heatmap is { columns, rows, values } with at most 24 columns by 31 rows, and values holding one array per row with one number or null per column. gantt is { rows } with at most 20 rows { id, label, start, end, status }, dates as YYYY-MM-DD, start on or before end, and status one of done, in_progress or upcoming.

Ids are lowercase slugs (letters, digits, - or _, at most 40 characters) and unique within their list. Every label and series name is at most 40 characters. Numbers are finite with an absolute value of at most 1e15. A type that would draw too many categories is refused (bar and stacked 24, barH and funnel 12, donut 8, line and area 120).

defaults takes any of these. People change the same settings on the card, and any setting you leave out starts at its usual value.

Setting Values
type Must equal the card’s type in defaults.
palette vibe, ocean, berry or mono.
xField An axis id of the selected measure (series data only).
yField A measure id (series data only).
range 4, 8 or 12 weeks or months, for the time charts.
grain week or month, for the time charts.
sort none, desc or asc, for barH, donut and funnel.
topN 0 (all), 3 or 5, for barH, donut and funnel.
legend true or false.
labels true or false, values drawn on the chart.
grid true or false.
{
"requestId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2e",
"streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2f",
"heading": "Weekly signups by plan",
"description": "Pro grew fastest after the pricing change on 27 July.",
"type": "line",
"data": {
"kind": "series",
"measures": [
{
"id": "signups",
"label": "Signups",
"rollup": "sum",
"axes": [
{
"id": "week",
"label": "Week",
"categories": [
{ "id": "w1", "label": "Jul 6", "date": "2026-07-06" },
{ "id": "w2", "label": "Jul 13", "date": "2026-07-13" },
{ "id": "w3", "label": "Jul 20", "date": "2026-07-20" }
],
"series": [
{ "id": "free", "name": "Free", "values": [120, 132, 128] },
{ "id": "pro", "name": "Pro", "values": [40, 46, 71] }
]
}
]
}
]
},
"defaults": { "palette": "ocean", "range": 8 },
"allowedTypes": ["line", "area", "bar", "stacked"]
}

A gauge is the smallest card:

{
"requestId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d30",
"streamId": "0197f2c4-5b1e-7c3a-9d2e-4f6a8b0c1d2f",
"heading": "Uptime this month",
"type": "gauge",
"data": {
"kind": "gauge",
"value": 99.2,
"target": 99.9,
"min": 95,
"max": 100,
"label": "Uptime %"
}
}

{ interactionId, messageId, chartType, created }. Nothing is read back automatically.

People change the view settings on the card (chart type, colors, fields, range, sort, labels) and the change is saved on the card for everyone, with a revision number that goes up on every save and on Reset. The data never changes. Your agent is not told, and no turn starts.

To see what people chose, call get_ui_interaction with the interactionId: the card is always submitted, there is no response, and input.savedSettings is { settings, revision }. Revision 0 is the card as you posted it. There is no tool that changes a card’s settings; to show something different, post a new card.

400 chat.chart_invalid_request carries details.issues, one entry per problem with the path of the field and a message. Common ones:

Problem Message names
A list is empty or over its limit The list, for example data.measures[0].axes[0].series.
A series has the wrong number of values The values of that series, with the expected and given counts.
A weekly date is not a Monday The date of that category.
The type cannot draw this data type, with the types that can.
A text is too long The field, for example description or a label.
savedSettings or an unknown field The field name.

Fix the listed fields and call again. Nothing was posted, so the same requestId is fine if the content you send is now valid.

409 chat.chart_request_conflict means the requestId was used for different content or its card was deleted: use a new one. 429 chat.chart_rate_limited means more than 5 new cards in a minute in that stream: wait the seconds given.