szum

MCP server

Source: https://szum.io/docs/mcp

Add Charts by Szum to ChatGPT or Claude, or connect other AI agents through MCP.

The Szum MCP server gives AI agents the current chart types, curated themes, examples, validation, rendering, and saved-chart tools they need to produce considered charts reliably.

Quick start

Add Charts by Szum from the ChatGPT or Claude directory. Other MCP clients connect to:

https://szum.io/mcp

Public discovery, validation, and preview tools work without authentication. Saved-chart tools require OAuth or a Bearer API key.

After connecting, ask for a chart in ordinary language:

Show quarterly revenue by region as an editorial column chart. Cite the source, preview it, and save the finished chart after I approve it.

The agent can discover the supported chart types, build and validate a request, render a temporary preview in compatible clients, or save a permanent document with stable image and embed links.

Connect from ChatGPT

Add to ChatGPT

1. Open the Charts by Szum listing in ChatGPT.
2. Follow the installation and connection prompts, reviewing the requested access.
3. Sign in to Szum when ChatGPT asks for account access.
4. Start a new conversation, select Charts by Szum with an @ mention, and describe your chart.

Use the published listing; no manual MCP server setup is needed. Availability depends on your ChatGPT account and workspace policy. Public discovery, validation, and previews work without Szum credentials; saving charts requires account access.

See OpenAI’s plugin guide for selecting a plugin and connecting its apps.

Connect from Claude

Add to Claude

1. Open the Charts by Szum listing in Claude’s Connectors Directory.
2. Choose Connect.
3. Authorize Szum when Claude asks for account access.

Anonymous previews work without a Szum account. Claude asks for access when you use tools that work with saved charts.

Connect from Claude Code

1. Choose a server name, replace SERVER_NAME in the command below, and run it in your terminal.
2. Open Claude Code and enter /mcp.
3. Select the server you added and complete the browser authentication flow.

claude mcp add --transport http SERVER_NAME https://szum.io/mcp

See the Claude Code MCP guide for connection and authentication options.

Connect from Cursor

1. Open your global ~/.cursor/mcp.json, or a project's .cursor/mcp.json.
2. Replace SERVER_NAME with your chosen server name, add the configuration below, and save the file.
3. Restart Cursor, then complete authentication when requested.

{
  "mcpServers": {
    "SERVER_NAME": {
      "url": "https://szum.io/mcp"
    }
  }
}

See Cursor's MCP configuration guide for the current setup options.

Connect from VS Code

1. Open the Command Palette and run MCP: Add Server.
2. Choose HTTP, paste the endpoint, and set the server name.
3. Choose whether to install it globally or in the current workspace.
4. Start the server, confirm that you trust it, and complete authorization when prompted.

{
  "servers": {
    "SERVER_NAME": {
      "type": "http",
      "url": "https://szum.io/mcp"
    }
  }
}

VS Code's MCP server guide covers workspace and user-profile configuration.

Install the agent skill

Agents that support Agent Skills, such as Claude Code, Codex, and Cursor, can also install the szum-charts skill. It tells the agent when to use Szum and teaches the validate, render, and save workflow, through these MCP tools when they are connected and through the HTTP API when they are not.

npx skills add https://szum.io

Discover supported charts

• list_chart_types returns the current chart families plus shared and family-specific fields.
• list_themes returns the curated themes and their intended uses, and for a signed-in connection the workspace's shared themes in workspaceThemes.
• get_examples({ chart_type?, purpose?, features?, example_id? }) returns complete current documents with stable IDs, a use_when explanation, and purpose/feature metadata. No filters returns the featured starters; any filter searches the complete catalog. All supplied filters intersect, and every requested feature must match.
• get_schema({ chart_type? }) returns the JSON Schema for the complete document; pass chart_type to keep only that family's config.
• validate_chart({ chart }) validates a JSON document or supported 2026-03-20 config without rendering or saving.

Use list_chart_types to choose a chart type and get_schema for its exact fields, rather than probing validate_chart for errors.

Example filter values are advertised directly in the tool's input schema. Purpose describes the chart question; features describe techniques such as annotations, references, intervals, normalization, and wide data. distribution means categorical frequencies, not automatic histogram binning. Use an example_id returned by a previous result for exact retrieval.

get_examples({ features: ["annotations"] });
get_examples({ chart_type: "scatter", features: ["intervals", "annotations"] });
get_examples({ chart_type: "waterfall", purpose: "change" });
get_examples({ purpose: "composition", features: ["normalized"] });
get_examples({ example_id: "grouped-wide" });

An empty result means no example satisfies every filter; remove one to broaden the search. Most examples use illustrative data; the Vinyl waterfall derives its changes from cited RIAA revenue reports. The cookbook displays the same catalog. Its missing-data example intentionally produces a gap warning.

Clients that read MCP resources also get szum://schema, the same document schema get_schema returns, and szum://llms-txt, the full authoring and API reference.

Work with charts

Need	Tool	Result
Discover chart families	list_chart_types	Current roles and family-specific fields
Find a starting point	get_examples	Ready-to-use current documents
Look up exact fields	get_schema	JSON Schema for the document, optionally for one chart type
Pick a theme	list_themes	Curated themes with their intended uses, and a signed-in workspace's shared themes
Check input only	validate_chart	Structured findings without image or storage effects
Preview a chart	render_chart	Interactive App preview, temporary public image URLs, and durable-input status
Keep and share a chart	save_chart	Permanent image, embed, editor, and Studio URLs
Find saved charts	list_charts	Paginated chart metadata and URLs, filterable by source, title, and author
Open a saved chart	get_chart	Metadata, URLs, and inline display when published
Read its definition	get_chart_document	Complete published document for inspection or reuse
Replace a saved chart	update_chart	New publication with the same id and URLs
Rename a saved chart	rename_chart	Updated library title without changing the document
Delete a saved chart	delete_chart	Permanent, retry-safe deletion
Restore App state	get_preview_state	Whether an App preview is still transient or was saved

Saved-chart tools require authentication. get_chart returns metadata and URLs, not the document. get_chart_document returns the published document and never substitutes a newer Studio draft. update_chart refuses to run while unpublished Studio changes exist, so it cannot discard newer work.

Validate, preview, then save

Validate each generated or changed input once before its next render, save, or update, and not again while it stays unchanged. A successful render returns the exact input to save next when no compatibility loss remains.

Errors block. Warnings must be shown to the user; set acknowledgeWarnings: true only after the user approves that exact input. Suggestions never block and are never applied automatically. A suggestedDocument is a complete, validated replacement; review it before using it, and validate again only if you change it.

In a Team workspace, findings with the workspace_rule code come from the workspace's chart rules. A rule set to Block is an error that refuses rendering, saving, and updating until the chart meets it; a rule set to Warn needs the same approval as any other warning.

render_chart({ request, acknowledgeWarnings? }) accepts a JSON string containing a current document or supported 2026-03-20 config. It stores a 1 hour preview and returns temporary image URLs. Its durableInput is either ready with the current document, or loss_acceptance_required with every compatibility loss code and no document that could bypass acceptance.

After the user approves the finished preview, save durableInput.document when its status is ready. For loss_acceptance_required, show every loss code, obtain explicit approval, then call save_chart with the original older config and the complete acceptLosses list. A compatible App offers its direct save action only for ready input. save_chart may reuse the App preview identity; otherwise send one stable idempotencyKey for the intended chart and reuse it on retries. The same key and document return the same chart. The same key with different content conflicts.

Shared themes

In a Team workspace, render_chart, save_chart, and update_chart accept sharedTheme, the name of one of the workspace's shared themes from list_themes. The chart takes the theme's values, and a saved chart stays linked to it, so its image and embed follow later edits to the theme.

When a document sets neither theme nor themeOverrides, render_chart and save_chart use the workspace's default theme. A preview in a shared theme returns its name as durableInput.sharedTheme; save it together with durableInput.document to keep the link. update_chart without sharedTheme keeps the chart's link unless the document sets a different theme of its own; get_chart_document returns the linked theme's values, so updating that document keeps the link. Pass sharedTheme: null to update_chart to end the link and keep the document's own theme.

Preview privacy and retention

Temporary image URLs are public capabilities: anyone holding the unguessable URL can fetch the chart during the retention window. Obtain explicit user consent before rendering sensitive, private, or non-public data.

In clients that support MCP Apps, the interactive preview can render from hidden result metadata without fetching a public static image. PNG, SVG, and fallback/open actions use /r/{id} URLs that remain available for 1 hour; each produced image may be cached for 1 hour.

Saved documents and older configs

save_chart and update_chart take a complete current ChartDocument or supported 2026-03-20 config as a JSON string in document. Send the exact validated current document, or the exact older input together with its approved loss codes.

update_chart keeps a chart's renamed library title unless you pass title; a chart whose title still comes from its document takes the new document's title.

An older config's validation result includes compatibility.classification and its codes. exact and normalized input renders and saves normally; lossy input renders, but saving needs every code in acceptLosses after the user approves them; unsupported input can be neither rendered nor saved. See older config compatibility for every code.

Tool failures

Tool failures return JSON text with status and an error object containing code, message, and retryable, and carry no structuredContent. Failures that need review add diagnostics, plus compatibility or suggestedDocument when they apply. A completed validate_chart call returns a validation result instead.

Automate on code and retryable, never on messages. A retryable storage or credential failure is temporary: report it as such rather than asking the user to reconnect.

Authentication

No credentials are needed to connect, inspect the design system, validate input, or create an anonymous preview. OAuth-capable clients authorize access when saving, listing, opening, reading, updating, renaming, or deleting charts from the user's library.

If you belong to a Team workspace, Szum asks which workspace the connection should use when you authorize it: Personal or one of your Team workspaces. Charts are saved to and listed from that workspace, and save_chart and list_charts name it in their results. To switch, disconnect Szum in your client and connect again. An API key always acts on the workspace it was created in.

If a client does not support OAuth, create an API key and send it as a Bearer token:

{
  "mcpServers": {
    "SERVER_NAME": {
      "type": "http",
      "url": "https://szum.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Keep keys out of shared project files. See Authentication for the complete model.

Usage and billing

The MCP endpoint allows 100 requests per second per IP, and each API key or OAuth connection also has its own limit of 30 per second.

An authenticated render_chart preview counts against the signed-in user's plan limit, and each image later produced from its temporary URL is another render. Anonymous interactive previews are free; their temporary image URLs use a separate allowance of 250 images per month, counted only when Szum produces an image rather than serving a cached one.

Discovery, examples, themes, validation, saved-chart metadata reads, and App preview-state restoration do not consume render quota.