MCP server

The rest of this site is about a model writing microcharts: a grammar it emits, a catalog it reads. This page is about a model calling them. @microcharts/mcp is a Model Context Protocol server that exposes three tools — find a chart for a question, get its exact props, render it to SVG — backed by the real library, not by a description of it.

It runs on your machine over stdio. Nothing is hosted, there is no key, and no data leaves the process your client spawns.

Emit, read, call

Three ways a model can end up with a correct chart. They stack; none replaces the others.

Emit is for a surface you control, where you can map a block to a component. Call is for a surface you don't — a chat reply, a terminal, an email draft — where the model needs the finished artwork rather than an instruction to draw it.

Add it to your client

The package ships a microcharts-mcp binary, so every client below spawns the same thing. No install step of your own — npx fetches it on first run.

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

claude mcp add microcharts -- npx -y @microcharts/mcp

{
  "mcpServers": {
    "microcharts": {
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

{
  "servers": {
    "microcharts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@microcharts/mcp"]
    }
  }
}

The three tools

They're designed to be called in order, but each stands alone.

find_microchart

You know the question; you don't know which of the 106 chart types answers it. Rank them.

{ "question": "is the error budget burning down?", "limit": 3 }

[
  {
    "slug": "error-budget",
    "name": "ErrorBudget",
    "tagline": "Are we burning the error budget too fast to survive the window?",
    "dataShape": "number[], budget remaining (0–1) per elapsed step; index 0 = 1.0",
    "why": "an SLO error budget in a KPI card"
  },
  {
    "slug": "burn-chart",
    "name": "BurnChart",
    "tagline": "Will we finish on time?",
    "dataShape": "{ plan: number[]; actual: number[] }, remaining work per period",
    "why": "a sprint burndown in a tab header"
  }
]

why is not a generated explanation — it's the bestFor phrase that actually matched, quoted back. An optional dataShape argument filters to the shape you already have.

get_microchart

Everything needed to wire one chart: import paths, its own props plus the shared grammar, best/avoid guidance, a copy-runnable example — and sample, that same example as JSON props.

{ "slug": "bullet" }

{
  "slug": "bullet",
  "staticImport": "@microcharts/react/bullet",
  "interactiveImport": "@microcharts/react/bullet/interactive",
  "dataShape": "value + target + bands",
  "encoding": { "channel": "position (measure length vs a target tick)", "precision": "high" },
  "bestFor": ["progress to goal", "SLA / budget vs target", "KPI with thresholds"],
  "example": { "code": "<Bullet value={72} target={80} bands={[50, 90]} title=\"Quota\" />" },
  "sample": { "value": 72, "target": 80, "bands": [50, 90], "title": "Quota" }
}

The two example forms exist for two different readers. example.code is JSX, for a human to paste. sample is JSON, for the model to hand straight to render_microchart — every chart takes its own shape, and guessing between number[], { label, value }[], and { open, high, low, close }[] is exactly where a model goes wrong.

render_microchart

Render to a self-contained SVG plus its generated alt text — for a surface that cannot run React.

{ "type": "sparkline", "data": [132, 148, 141, 165, 159, 182] }

{
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" class=\"mc-root mc-spark\" …><style>…</style>…</svg>",
  "summary": "Trending up 38%. Range 132 to 182. Last value 182.",
  "mimeType": "image/svg+xml",
  "width": 80,
  "height": 20,
  "library": "0.8.0"
}

That's this, as a real component on this page — the same geometry, the same summary:

The default format: "svg" embeds the stylesheet inside the SVG, so the mark is correct dropped into a surface with no CSS of its own. Pass format: "bare" when the page already loads @microcharts/react/styles.css.

summary is not written by the tool. It is the chart's own accessible name, read back out of the rendered markup — the same sentence a screen reader speaks. See Accessibility for how it's generated.

Two resources

Alongside the tools, the server publishes two read-only resources:

• microcharts://catalog — every chart type with its props, data shape, encoding, and the @microcharts/react version the snapshot was cut from.
• microcharts://agent-setup — the same paste-and-run setup prompt served at /agent-setup.md, for when the assistant should wire the library into a repo rather than render a one-off.

What it looks like in practice

import { microchartsTools } from "@microcharts/mcp/ai-sdk";import { streamText } from "ai";const result = streamText({  model,  tools: microchartsTools, // find_microchart · get_microchart · render_microchart  prompt: "Summarise this quarter and show the revenue trend as a chart.",});

How it behaves

A model mid-reply cannot promise clean numbers, and a tool that guesses is worse than one that refuses. The rule here is that every call ends in one of two places: an honest mark, or a named error. Never a plausible wrong answer.

Messy data still renders

Degenerate input is a documented case, not a failure. The chart renders and the summary says what actually happened — these are the real generated sentences:

The chart never invents a number to fill a hole, and the sentence never claims more than the data supports. Same guarantees as the components — see Accessibility for the full matrix.

Calls it refuses, and what it says

Refusals come back as tool errors with the fix in the message, so the model can correct itself in one turn instead of retrying blind:

The size limits are deliberate. A microchart is a word-sized mark; a series big enough to produce megabytes of markup is a mistake upstream, and returning it would blow the model's context rather than help it.

What comes back

Every render carries role="img" and the generated accessible name, so the mark is usable the moment it lands.

• format: "svg" (default) embeds the stylesheet inside the SVG. The result is genuinely standalone — and because the real stylesheet comes with it, the mark still answers prefers-color-scheme, forced-colors, and prefers-reduced-motion in whatever surface it ends up in. A chart pasted into a dark-themed client is drawn for dark.
• format: "bare" drops the embedded CSS for a page that already loads @microcharts/react/styles.css. Far smaller per response, and the right choice inside your own app.
• mimeType is image/svg+xml for most charts. Delta and TokenConfidence are inline text marks, so they come back as text/html with width/height of 0 — they size to the font around them, not to a pixel box.
• library is the @microcharts/react version that drew it.

Props that do cross a tool call

Anything JSON can express: data, value, domain, title, summary, color, categorical colors, label, dots, width, height, className, style, id, and positive. Two are worth calling out:

• locale — "de-DE" gives "Range 1.200 to 1.800.". Number formatting is fully available.
• format — the Intl.NumberFormatOptions half of the union works: { "style": "currency", "currency": "EUR" } yields "Range €1,200.00 to €1,800.00.". The callback half does not (see below).

Passing id switches the chart from aria-label to <title>/<desc> + aria-labelledby, exactly as the component does; summary still comes back correct.

What it can't do

Worth knowing before you reach for it, so you reach for the component instead:

• It renders the static chart. No hover, keyboard roving, touch scrub, or selection, and animate has no meaning. Those live on the /interactive entry — get_microchart returns interactiveImport so an agent can wire it up in code.
• No annotations. Threshold, TargetZone, Marker, and Callout are React children; JSON has no children.
• No function props. Formatter callbacks and event handlers can't cross a tool call. Use locale and the format options object for numbers, or set summary to supply the sentence yourself.
• No raster output. You get an SVG or HTML string, never a PNG. Anything that renders SVG will show it; anything that won't needs a converter on your side.
• stdio only. The server is spawned by your client on your machine. There is no hosted endpoint and no HTTP transport, by design — it is also why nothing you chart leaves the process.
• It doesn't touch your project. No files written, no dependencies installed. To wire the library into a repo, use the agent setup prompt instead.
• Chart props are a closed set. Arbitrary data-* or aria-* attributes are not forwarded — a deliberate library decision, not a transport limit.

Versioning and compatibility

The server carries a snapshot of the catalog and the stylesheet, cut from a specific @microcharts/react release. That version is stamped on the microcharts://catalog resource and returned on every render as library, so a chart you generate can always be traced to the code that drew it.

The two version lines move independently: @microcharts/mcp tracks its own changes, and pulls in a compatible library automatically. Pin the server, not the library, if you need a reproducible render.

Adding a chart

For contributors: nothing about a new chart is written by hand here. The server's catalog is generated from the same chart registry that drives this site, and a test re-derives it from those sources on every run — so a chart that lands in the library without the snapshot being regenerated fails CI rather than shipping a server that has never heard of it. The rendered sample for every stable chart is exercised in that same suite.

The package lives at @microcharts/mcp. If your assistant doesn't speak MCP, the Quickstart has a paste-and-run prompt that teaches it the library directly, and AI-native covers the grammar it emits.