MCP Tools Reference

The InstaCharts MCP server gives AI apps 14 tools. Your AI assistant picks the right tool based on what you ask, so you don’t need to name tools in your prompts. This page lists each tool, what it does and the inputs it takes, which helps when you want to understand what an assistant can do or are building your own agent.

MCP server URL: https://api.instacharts.io/mcp

How the data is organized

Data lives in sheets, sheets live in workspaces, and each chart is built on one sheet. A typical flow is:

1. list_workspaces to pick a workspace.
2. create_sheet, import_from_url or create_upload_link to add the data (or list_sheets and read_sheet to use data already in InstaCharts).
3. update_chart to set up the sheet’s first chart, or create_chart for another one.
4. get_chart_image to check how the chart looks.
5. share_chart for a public link and embed code.

Columns can be named by their header text or by their id. Each new sheet comes with a blank first chart, returned as firstChartId, which the assistant sets up with update_chart.

Tool summary

Tool	What it does	Permission	Task
list_workspaces	Lists your workspaces and whether you can edit in each one	View	Free
list_sheets	Lists the sheets in a workspace with their size	View	Free
read_sheet	Reads a sheet’s columns and a page of its rows	View	Free
list_charts	Lists the charts built on a sheet	View	Free
get_chart_image	Renders a chart as a PNG image	View	1 task
create_sheet	Creates a sheet from CSV text or rows	Edit	1 task
import_from_url	Creates a sheet from a data file at a public link	Edit	1 task
create_upload_link	Returns a one-time link for uploading a data file	Edit	1 task for the upload
add_rows	Adds up to 1,000 rows to a sheet	Edit	1 task
update_rows	Changes cells in existing rows	Edit	1 task
delete_rows	Deletes rows from a sheet	Edit	1 task
create_chart	Creates a chart on a sheet	Edit	1 task
update_chart	Changes a chart’s columns, type and settings	Edit	1 task
share_chart	Makes a chart public and returns its link and embed code	Edit	1 task

Tools that need the edit permission only appear when you approve Create and edit your sheets, charts and embeds while connecting the AI app. See Permissions and Tasks.

Read tools

list_workspaces

Lists the workspaces your account can use, and whether you can edit in each one. This is where the assistant finds a workspaceId. Only workspaces on a paid plan are listed.

list_sheets

Lists the sheets (data tables) in a workspace along with their size.

Input	Required	Description
workspaceId	Yes	The workspace to list

read_sheet

Reads a sheet’s columns (id, name and type) and a page of its rows. Each row has a rowId that update_rows and delete_rows use.

Input	Required	Description
sheetId	Yes	The sheet to read
offset	No	Rows to skip. Default 0
limit	No	Rows to return. Default 100, at most 1,000

list_charts

Lists the charts built on a sheet.

Input	Required	Description
sheetId	Yes	The sheet whose charts to list

get_chart_image

Renders a chart as a PNG image so the assistant can see how it looks. Counts as one task.

Input	Required	Description
chartId	Yes	The chart to render

Sheet tools

create_sheet

Creates a sheet in a workspace from CSV text or an array of rows, with the header row first. Column types (text, number, date, percent, currency) are detected from the values, and the workspace’s plan limits the rows and columns. Returns the new sheet with its columns and firstChartId.

Input	Required	Description
workspaceId	Yes	The workspace for the new sheet
name	No	Sheet name, up to 100 characters
csv	One of csv or rows	Comma separated text with a header row
rows	One of csv or rows	Rows of cell values, header row first

This tool suits small datasets. For a file at a public link use import_from_url, and for a local file or more than a few hundred rows use create_upload_link.

import_from_url

Creates a sheet from a data file at a public web address. InstaCharts downloads the file itself, so the data never has to pass through the conversation. Good sources include an open data portal’s CSV or JSON export link, a raw file on GitHub (raw.githubusercontent.com) or a Google Sheet published to the web as CSV.

The link has to download the file directly, be public and use https://. A link to a web page that displays the data is refused. CSV, TSV, Excel, OpenDocument, Numbers and JSON files work, up to the plan’s file size. An Excel file with several pages makes one sheet per page.

Input	Required	Description
workspaceId	Yes	The workspace for the new sheet
url	Yes	The https:// address of the file
name	No	Sheet name. Without one, the sheet takes the file’s name

To keep a sheet in sync with a link from the InstaCharts app, see Import and Sync from a Link.

create_upload_link

Returns a one-time upload link (uploadUrl) that turns a data file into a new sheet. This is meant for files and datasets too large to send as CSV text. The file has to be sent within 15 minutes as an HTTP POST with multipart/form-data, with the file in a field named file:

curl -F "file=@sales.csv" <uploadUrl>

On Windows PowerShell use curl.exe. CSV, TSV, Excel, OpenDocument, Numbers and JSON files work, up to the size in maxFileSizeMB. The upload’s response is the new sheet, the same as create_sheet returns. Each link works once. Creating the link is free, and the upload counts as one task.

This tool needs an AI app that can send a file, such as one that can run commands (ex: Claude Code) or make HTTP requests.

Input	Required	Description
workspaceId	Yes	The workspace for the new sheet
name	No	Sheet name. Without one, the sheet takes the file’s name

add_rows

Appends up to 1,000 rows to a sheet. Each row is an object of column name (or id) and value. Every chart on the sheet updates with the new rows.

Input	Required	Description
sheetId	Yes	The sheet to add to
rows	Yes	Ex: [{"Region": "East", "Sales": 120}]

update_rows

Changes cells in existing rows, found by the rowId from read_sheet. Only the columns sent are changed.

Input	Required	Description
sheetId	Yes	The sheet to change
changes	Yes	Up to 1,000 changes. Ex: [{"rowId": 3, "values": {"Sales": 150}}]

delete_rows

Deletes rows by the rowId from read_sheet. Deleted rows can’t be recovered.

Input	Required	Description
sheetId	Yes	The sheet to change
rowIds	Yes	Up to 1,000 row ids

Chart tools

create_chart

Creates a chart on a sheet. The workspace’s saved theme, fonts, colors and locale are applied.

• x is the category or date column.
• y is the number column being measured. Without y, the chart counts rows for each x value.
• groupBy splits the values into series for grouped and stacked chart types. On a heatmap it is the second category.
• aggregate defaults to sum for a number column and count for other columns.

Input	Required	Description
sheetId	Yes	The sheet to chart
type	Yes	The chart type (see below)
x	Yes	Column name or id for the x axis
y	No	Column name or id for the values
groupBy	No	Column name or id that splits the data into series
aggregate	No	sum, count, average, median, min, max, distinct, valid or missing. See Aggregation
dateGrouping	No	year, quarter, month, week, day, monthOfYear or dayOfWeek
title	No	Chart title
subtitle	No	Chart subtitle
caption	No	Text under the chart
name	No	Chart name in the sheet’s chart list
colorScheme	No	One of the InstaCharts color schemes
sort	No	auto, x, y or none
sortDescending	No	true puts the largest value or last label first
horizontal	No	Bar charts only. Horizontal bars suit long category names
width, height	No	Chart size in pixels, 200 to 3,000
gaugeMin, gaugeMax, gaugeTarget	No	Gauge charts only

Chart types

type	Chart	Uses groupBy
bar	Bar Chart	No
stackedBar	Stacked Bar Chart	Yes
groupedBar	Grouped Bar Chart	Yes
line	Line Chart	No
groupedLine	Grouped Line Chart	Yes
scatter	Scatterplot Chart	No
groupedScatter	Grouped Scatterplot Chart	Yes
area	Area Chart	No
groupedArea	Grouped Area Chart	Yes
pie	Pie Chart	No
radar	Radar Chart	Yes
heatmap	Heatmap Chart	Yes
mekko	Mekko Chart	Yes
gauge	Gauge Chart	No
groupedGauge	Grouped Gauge Chart	Yes

Date grouping

dateGrouping applies to date columns on the x axis. year, quarter, month, week and day follow the timeline. monthOfYear and dayOfWeek combine every year into 12 months or 7 weekdays. When it isn’t set, dates spanning more than 5 years are grouped by year, and dates spanning 2 to 5 years are grouped by month.

update_chart

Changes an existing chart, including the sheet’s blank first chart. Only the fields sent are changed. It takes chartId plus any of the create_chart inputs. Send null for groupBy or y to clear it.

Input	Required	Description
chartId	Yes	The chart to change

share_chart

Makes a chart public and returns its share link (shareUrl), its embed URL and the iframe embed code. Anyone with the link can see the chart. Send active: false to make the chart private again.

Input	Required	Description
chartId	Yes	The chart to share
active	No	true shares the chart (default), false stops sharing

Read more about sharing charts and embedding charts in a website.

Related

• Connect AI Apps with the MCP Server - set up Claude, ChatGPT and Claude Code
• Tasks - how tasks are counted
• All Chart Types - every chart InstaCharts can make