list_chart_output_examples
Return the ids of all built-in chart/card JSON specs shipped with this MCP package.
Use this tool when: you are about to call render_card and are unsure of the spec shape; you have received a 400 error from render_card; you want to browse available example layouts before choosing one.
Do NOT skip this step when building full card compositions — guessing field names causes 400 errors.
Returns: a plain-text list of example ids (one per line). Pass any id to get_chart_example to retrieve the full, API-ready JSON body.
Example invocation: list_chart_output_examples() → ["mrr-breakdown", "weekly-sales-by-plan", ...]
get_chart_example
Return the complete JSON body for a named built-in example spec — identical to examples/<id>.json on disk.
Use this tool when: you need a valid API body to start from before calling render_card; render_card returned HTTP 400; you want to verify the exact field names for header, kpiStrip, footer, data, options, or theme.
Do NOT hand-author a full card spec from memory — always start from this example and edit values only.
Returns: the full JSON text of the example, ready to pass as the `spec` argument to render_card. Field structure must be preserved; only values should change.
Errors: throws if the id is not found — call list_chart_output_examples first to see valid ids.
Example invocation: get_chart_example({ example: "mrr-breakdown" }) → { type: "bar", data: {...}, header: {...}, ... }
render_chart
Render a Chart.js-style chart from structured labels and datasets and return it as an inline base64-encoded image.
Use this tool when: you have pre-structured numeric data with explicit labels and datasets; you want a simple chart (line, bar, pie, doughnut, radar, polarArea) returned directly as an image in chat; you want to optionally add Chart-Output dashboard extras (dark background, KPI strip, header, footer) via the extensions field without building a full card spec by hand.
Do NOT use this tool when: you need a stable URL to embed in HTML or email → use render_chart_url instead; you have raw or natural-language data without structured labels/datasets → use render_chart_ai instead; you need a full branded card with header, footer, KPI strip, and theme → use render_card instead.
Behavior: this tool makes a remote API call to Chart-Output and may consume render credits.
Returns: an inline base64 image at the requested dimensions and format, plus a confirmation text string showing actual width×height and format. The image content-type matches the format parameter (image/png by default).
Errors: 401 — CHART_OUTPUT_API_KEY is missing or invalid; set the key in the MCP server env and retry. 400 — malformed spec, most often a mismatch between labels length and datasets[].data length, or an unsupported field value. 429 — rate-limited; retry with exponential backoff and honor Retry-After if present. Network error — chart-output.com is unreachable or timed out.
Example: render_chart({ type: "bar", labels: ["Q1","Q2","Q3","Q4"], datasets: [{ label: "Revenue", data: [12000, 15000, 18000, 22000], backgroundColor: "#4F81BD" }], title: "2024 Revenue", width: 800, height: 400 })
render_chart_url
Render a Chart.js-style chart from structured labels and datasets and return a stable CDN URL string instead of image bytes.
Use this tool when: you need to embed a chart in an HTML page, markdown document, or email via an <img> src attribute; you need to pass a chart URL to another tool or API; you want to avoid sending large base64 image blobs in the conversation.
Do NOT use this tool when: you want the image displayed inline in chat → use render_chart instead; you have raw or natural-language data → use render_chart_ai instead; you need a full branded card → use render_card instead.
Behavior: this tool makes a remote API call to Chart-Output, may consume render credits, and returns a publicly accessible CDN URL.
Returns: a plain text string containing a single HTTPS CDN URL pointing to the rendered chart image (e.g. "https://cdn.chart-output.com/..."). The URL is publicly accessible and stable for the lifetime of the render.
Errors: 401 — CHART_OUTPUT_API_KEY is missing or invalid; set the key in the MCP server env. 400 — malformed spec, most often a labels/data length mismatch or unsupported field value. 429 — rate-limited; retry with exponential backoff and honor Retry-After if present. Network error — chart-output.com is unreachable or timed out.
Example: render_chart_url({ type: "line", labels: ["Jan","Feb","Mar"], datasets: [{ label: "MAU", data: [12000, 18000, 24000] }], title: "Monthly Active Users" }) → "https://cdn.chart-output.com/abc123.png"
render_card
Render a full branded card composition — header, KPI strip, chart, and footer — and return it as an inline base64-encoded image.
Use this tool when: you need a production-grade dashboard layout with a header (title, subtitle, badge), KPI metric row, themed background, footer, or brand kit; you want to send the full /api/v1/render JSON body verbatim to Chart-Output.
Do NOT use this tool when: you only need a simple chart without branding → use render_chart instead; you need a URL rather than inline bytes → use render_card_url for full branded cards or render_chart_url for simple charts; you have natural-language data → use render_chart_ai instead.
Behavior: this tool makes a remote API call to Chart-Output and may consume render credits.
IMPORTANT — always start from an example spec: call get_chart_example("mrr-breakdown") (or list_chart_output_examples to browse all ids) and modify values only. Do NOT hand-author the full spec from memory; incorrect field names cause HTTP 400.
Returns: an inline base64 image at the format and dimensions defined in the spec, plus a confirmation text string with dimensions and format.
Errors: 400 — malformed or missing required spec fields; the server will auto-retry once after normalizing common structural issues (root labels/datasets → data object). 401 — API key missing or invalid. 429 — rate-limited; retry with exponential backoff and honor Retry-After if present. returnUrl in spec — not allowed; render_card returns inline images only; omit returnUrl from the spec.
Limitations: does not support returnUrl; inline image only. For the full field reference see https://www.chart-output.com/docs/card-composition.
Example: render_card({ spec: { ...get_chart_example("mrr-breakdown"), header: { title: "Q1 Report" } } })
render_card_url
Render a full branded card composition — header, KPI strip, chart, and footer — and return a stable CDN URL string instead of image bytes.
Use this tool when: you need an openable, shareable, or downloadable URL for a production-grade dashboard layout with a header, KPI metric row, themed background, footer, or brand kit; you want to send the full /api/v1/render JSON body verbatim to Chart-Output.
Do NOT use this tool when: you want the image displayed inline in chat → use render_card instead; you only need a simple Chart.js labels/datasets chart → use render_chart_url instead; you have natural-language data → use render_chart_ai instead.
Behavior: this tool makes a remote API call to Chart-Output, may consume render credits, and returns a publicly accessible CDN URL.
IMPORTANT — always start from an example spec: call get_chart_example("mrr-breakdown") (or list_chart_output_examples to browse all ids) and modify values only. Do NOT hand-author the full spec from memory; incorrect field names cause HTTP 400.
Returns: a plain text string containing a single HTTPS CDN URL pointing to the rendered full card image. The URL is publicly accessible and stable for the lifetime of the render.
Errors: 400 — malformed or missing required spec fields; the server will auto-retry once after normalizing common structural issues (root labels/datasets → data object). 401 — API key missing or invalid. 429 — rate-limited; retry with exponential backoff and honor Retry-After if present.
Example: render_card_url({ spec: { ...get_chart_example("mrr-breakdown"), header: { title: "Q1 Report" } } }) → "https://cdn.chart-output.com/abc123.png"