Datasets

An agent brings its own data with upload_file: a table or text file is parsed into datasets, and an image or PDF is stored as a source you read yourself. list_datasets returns your own uploads plus the tables wired into dashboards you can view. To chart one, wire a widget pipeline to mcpId mcp-vistazo, toolName read_dataset: it is the only Vistazo tool a pipeline may call.

Additive write

Bring a file into a workspace so its tables become datasets you can chart — the way to chart data you have locally instead of pasting rows into a widget config (which freezes the chart at today's numbers). name is the filename WITH its extension, which decides the type: csv, tsv, xlsx, json, txt and md are PARSED, and every table in them becomes a dataset (each xlsx sheet its own); png, jpg, webp, gif and pdf are stored as SOURCES — Vistazo never reads an image with a model, and a PDF gives up only its text layer. To chart a scan, a photo or a screenshot: read the table out of it yourself, upload the scan, then upload the table as a csv naming the scan's fileId as sourceFileId, which records where the numbers came from. Two ways to send the bytes. With no content, the reply carries an uploadUrl good for ONE upload within 15 minutes: send the file with curl -T <path> "<uploadUrl>" (a PUT with a Content-Length), then call get_upload. For a small text file (up to 64 KB) with no shell to hand, pass it as content and the reply is get_upload's. Caps: 10 MB for an image, 20 MB otherwise, all of it on YOUR storage quota. The file is yours alone until a dashboard uses it, in either of two ways: SHOWN (add_widget type file, or ![alt](attachment:<fileId>) in a markdown widget — images and PDFs), or CHARTED (a widget pipeline reading one of its datasets with read_dataset). Everyone who can view that dashboard can then open the file, and the public too when the dashboard is public. Needs full workspace membership — guests and view-only members cannot upload.

Read-only

Check a file you sent with upload_file. status is uploading | extracting | ready | failed | deleted, and tables lists what was found as {name, columns, rowCount, datasetId} — one per xlsx sheet, named for it — and a datasetId goes straight into describe_dataset, read_dataset or a widget pipeline. Sheets that became no dataset (blank, or past the 20-sheet or 100,000-row workbook limits) are listed in skippedSheets with the reason. Waits up to 3 seconds for extraction to finish; a big spreadsheet or PDF can take longer, so call again while status is extracting. uploading means the bytes have not arrived — send them to the uploadUrl first. An image or a scanned PDF lands ready with no tables: it is a source, stored unread, so read its table yourself and upload that. A ready file the parser could not turn into a table (a .json with a syntax error, or valid JSON that is not an array of flat row objects) carries a note saying which, and the repair. A failure says why in error; errorCode: password is a locked PDF, and the fix is an unlocked copy. Only the uploader can see an upload.

Destructive write

Delete a file uploaded with upload_file. The bytes go and your storage is credited at once; every dataset made from it is marked deleted rather than erased, so a chart wired to one says "Source file deleted" instead of breaking silently. There is no undo — re-upload to restore. Pass the fileId upload_file returned: that id IS the confirmation, so resolve it first (get_upload) when unsure. The uploader may delete their file, and so may a workspace admin.

Read-only

List your own uploaded tables plus the tables wired into dashboards you can view — tables extracted from uploaded files (CSV, spreadsheets, JSON, and tables found in PDFs/screenshots). Returns {id, workspaceId, name, columns, rowCount, updatedAt, deleted} per dataset; chart one by wiring mcpId 'mcp-vistazo', toolName 'read_dataset' (not in list_mcp_connections). THE DISCOVERY CALL: dataset ids are opaque and never guessable, so start here (or take the id the user's attached file gave you) before describe_dataset / read_dataset. deleted: true means the source file was deleted — the columns still describe what it held, but reading it fails; wire a chart to a live dataset instead. Pass workspaceId to narrow to one workspace; a workspace this connection was not granted is refused, not silently empty, and omitting it on a connection reaching several workspaces is refused (workspace_ambiguous). Carry the workspaceId a dataset comes back with into describe_dataset / read_dataset — that is the workspace the call is billed to.

Read-only

Inspect one dataset before charting it: its column names and inferred types (string | number | date | boolean), its row count, and a 5-row SAMPLE of the actual data. Call this between list_datasets and read_dataset — the sample is what tells you whether a column labelled date really holds dates, which column is the measure, and what the category values look like, so read_dataset's columns/where/orderBy can be written once instead of guessed at. Cheap: it reads only the head of the file. Pass the workspaceId list_datasets reported for this dataset: it is the workspace the call is billed to, and without it a connection covering several workspaces is refused with the list to pick from.

Read-only

Read rows from a dataset — the tool a WIDGET is wired to. Returns {columns, rows, total}: rows are objects keyed by column name with values already coerced to the column's type (numbers as numbers, dates as ISO strings, empty cells as null), and total is how many rows matched before limit. Narrow server-side rather than client-side: columns picks the fields to return, where filters (an AND of {column, op, value} with op eq | neq | gt | gte | lt | lte | in | contains — in takes an array, contains is a case-insensitive substring test on the text form), orderBy sorts ({column, dir}), and limit caps the result (default 5000). When building a chart, wire the widget's pipeline to THIS tool as mcpId 'mcp-vistazo', toolName 'read_dataset', with the filters it needs; the transform's rawResponse is that same {columns, rows, total}. Never paste rows into the widget's config, or the chart freezes at today's data and stops following the file. If the source file was deleted the call fails with dataset_deleted, naming the file and who removed it; the fix is a re-upload, not a retry. Pass the workspaceId list_datasets reported for this dataset: it is the workspace the call is billed to, and without it a connection covering several workspaces is refused with the list to pick from.